OSCAR-CLI provides a command line interface to interact with OSCAR clusters in a simple way. It supports service management, workflows definition from FDL (Functions Definition Language) files and the ability to manage files from OSCAR's compatible storage providers (MinIO, Amazon S3 and Onedata). The folder example-workflow contains all the necessary files to create a simple workflow to test the tool.

Download

Releases

The easy way to download OSCAR-CLI is through the github releases page. There are binaries for multiple platforms and OS. If you need a binary for another platform, please open an issue.

Install from source

If you have go installed and configured, you can get it from source directly by executing:

go install github.com/grycap/oscar-cli@latest

Available commands

The documentation is available on OSCAR's web for CLI. A video tutorial is available on YouTube.

• apply
• cluster
  • add
  • default
  • info
  • list
  • delete
• hub
  • list
  • deploy
  • validate
• service
  • get
  • list
  • delete
  • run
  • logs list
  • logs get
  • logs delete
  • get-file
  • put-file
  • list-files
• bucket
  • list
• interactive
• version
• help

apply

Apply a FDL file to create or edit services in clusters.

Usage:
  oscar-cli apply FDL_FILE [flags]

Aliases:
  apply, a

Flags:
      --config string   set the location of the config file (YAML or JSON)
  -c, --cluster string  override the cluster id defined in the FDL file
  -h, --help            help for apply

cluster

Manages the configuration of clusters.

Subcommands

add

Add a new existing cluster to oscar-cli.

Usage:
  oscar-cli cluster add IDENTIFIER ENDPOINT {USERNAME {PASSWORD | --password-stdin} | --oidc-account-name ACCOUNT} [flags]

Aliases:
  add, a

Flags:
      --disable-ssl                disable verification of ssl certificates for the added cluster
  -h, --help                       help for add
  -o, --oidc-account-name string   OIDC account name to authenticate using oidc-agent. Note that oidc-agent must be started and properly configured
                                   (See: https://indigo-dc.gitbook.io/oidc-agent/)
      --password-stdin             take the password from stdin

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

default

Show or set the default cluster.

Usage:
  oscar-cli cluster default [flags]

Aliases:
  default, d

Flags:
  -h, --help         help for default
  -s, --set string   set a default cluster by passing its IDENTIFIER

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

info

Show information of an OSCAR cluster.

Usage:
  oscar-cli cluster info [flags]

Aliases:
  info, i

Flags:
  -c, --cluster string   set the cluster
  -h, --help             help for info

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

list

List the configured OSCAR clusters.

Usage:
  oscar-cli cluster list [flags]

Aliases:
  list, ls

Flags:
  -h, --help   help for list

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

delete

Delete a cluster from the configuration file.

Usage:
  oscar-cli cluster delete IDENTIFIER [flags]

Aliases:
  delete, d, del, remove, rm

Flags:
  -h, --help   help for delete

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

hub

Browse curated service definitions published in OSCAR Hub.

Subcommands

list

List curated OSCAR services available in the Hub.

Usage:
  oscar-cli hub list [flags]

Aliases:
  list, ls

Flags:
      --json          print the list in JSON format
      --owner string  GitHub owner that hosts the curated services (default "grycap")
      --path string   subdirectory inside the repository that contains the services
      --ref string    Git reference (branch, tag, or commit) to query (default "main")
      --repo string   GitHub repository that hosts the curated services (default "oscar-hub")

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

deploy

Deploy a curated OSCAR service into a configured cluster.

Usage:
  oscar-cli hub deploy SERVICE-SLUG [flags]

Flags:
  -c, --cluster string  set the cluster
      --local-path string  use a local directory containing the RO-Crate metadata instead of fetching it from GitHub
      --owner string    GitHub owner that hosts the curated services (default "grycap")
      --path string     subdirectory inside the repository that contains the services
      --ref string      Git reference (branch, tag, or commit) to query (default "main")
  -n, --name string     override the OSCAR service name during deployment
      --repo string     GitHub repository that hosts the curated services (default "oscar-hub")

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

Default curated source: https://github.com/grycap/oscar-hub/tree/main

validate

Run the acceptance tests defined in a curated RO-Crate against a deployed service.

Usage:
  oscar-cli hub validate SERVICE-SLUG [flags]

Flags:
  -c, --cluster string   set the cluster
      --local-path string  use a local directory containing the RO-Crate metadata instead of fetching it from GitHub
      --owner string     GitHub owner that hosts the curated services (default "grycap")
      --path string      subdirectory inside the repository that contains the services
      --ref string       Git reference (branch, tag, or commit) to query (default "main")
  -n, --name string      override the OSCAR service name during validation
      --repo string      GitHub repository that hosts the curated services (default "oscar-hub")

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

service

Manages the services within a cluster.

Subcommands

get

Get the definition of a service.

Usage:
  oscar-cli service get SERVICE_NAME [flags]

Aliases:
  get, g

Flags:
  -c, --cluster string   set the cluster
  -h, --help             help for get

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

list

List the available services in a cluster.

Usage:
  oscar-cli service list [flags]

Aliases:
  list, ls

Flags:
  -c, --cluster string   set the cluster
  -h, --help             help for list

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

delete

Remove a service from the cluster.

Usage:
  oscar-cli service delete SERVICE_NAME... [flags]

Aliases:
  delete, d, del, remove, rm

Flags:
  -c, --cluster string   set the cluster
  -h, --help             help for delete

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

run

Invoke a service synchronously (a Serverless backend in the cluster is required).

Usage:
  oscar-cli service run SERVICE_NAME {--file-input | --text-input} [flags]

Aliases:
  run, invoke, r

Flags:
  -c, --cluster string      set the cluster
  -e, --endpoint string     endpoint of a non registered cluster
  -f, --file-input string   input file for the request
  -h, --help                help for run
  -o, --output string       file path to store the output
  -i, --text-input string   text input string for the request
  -t, --token string        token of the service


Global Flags:
      --config string   set the location of the config file (YAML or JSON)

logs list

List the logs from a service.

Usage:
  oscar-cli service logs list SERVICE_NAME [flags]

Aliases:
  list, ls

Flags:
  -h, --help             help for list
  -s, --status strings   filter by status (Pending, Running, Succeeded or Failed), multiple values can be specified by a comma-separated string

Global Flags:
  -c, --cluster string   set the cluster
      --config string    set the location of the config file (YAML or JSON)

logs get

Get the logs from a service's job.

Usage:
  oscar-cli service logs get SERVICE_NAME [JOB_NAME] [flags]

Aliases:
  get, g

Flags:
  -h, --help              help for get
  -l, --latest            get logs from the most recent job
  -t, --show-timestamps   show timestamps in the logs

Global Flags:
  -c, --cluster string   set the cluster
      --config string    set the location of the config file (YAML or JSON)

logs delete

Delete a service's job along with its logs.

Usage:
  oscar-cli service logs delete SERVICE_NAME {JOB_NAME... | --succeeded | --all} [flags]

Aliases:
  delete, d, del, remove, rm

Flags:
  -a, --all         remove all logs from the service
  -h, --help        help for remove
  -s, --succeeded   remove succeeded logs from the service

Global Flags:
  -c, --cluster string   set the cluster
      --config string    set the location of the config file (YAML or JSON)

get-file

Get a file from a service's storage provider.

The STORAGE_PROVIDER argument follows the format STORAGE_PROVIDER_TYPE.STORAGE_PROVIDER_NAME, being the STORAGE_PROVIDER_TYPE one of the three supported storage providers (MinIO, S3 or Onedata) and the STORAGE_PROVIDER_NAME is the identifier for the provider set in the service's definition. If STORAGE_PROVIDER is not provided, the first output provider defined in the service is used. Passing --download-latest-into[=PATH] fetches the newest object detected under the provided remote path. When PATH refers to a directory (or ends with a path separator) the file is saved there keeping its original filename. If PATH points to a file (for example, has an extension), that exact local filename is used. If REMOTE_PATH is omitted while using --download-latest-into, the default output path configured for that provider is used instead.

File downloads display a progress bar whenever the transfer size is known. Use --no-progress to disable the bar. On success the command prints the absolute path to the downloaded file.

Usage:
  oscar-cli service get-file SERVICE_NAME [STORAGE_PROVIDER] [REMOTE_PATH] [LOCAL_FILE] [flags]

Aliases:
  get-file, gf

Flags:
  -c, --cluster string        set the cluster
  -h, --help                  help for get-file
      --download-latest-into[=PATH]
                              download the most recent file (optionally place it inside PATH when it is a directory, or use PATH as the exact filename)
      --no-progress           disable progress bar output

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

put-file

Put a file in a service's storage provider.

The STORAGE_PROVIDER argument follows the format STORAGE_PROVIDER_TYPE.STORAGE_PROVIDER_NAME, being the STORAGE_PROVIDER_TYPE one of the three supported storage providers (MinIO, S3 or Onedata) and the STORAGE_PROVIDER_NAME is the identifier for the provider set in the service's definition. If STORAGE_PROVIDER is not provided, the command defaults to minio.default. If REMOTE_FILE is not provided, the file is uploaded under the input path configured for that provider using the local file name.

File uploads display a progress bar when the local file size is known. Use --no-progress to disable the bar.

Usage:
  oscar-cli service put-file SERVICE_NAME [STORAGE_PROVIDER] LOCAL_FILE [REMOTE_FILE] [flags]

Aliases:
  put-file, pf

Flags:
  -c, --cluster string   set the cluster
      --no-progress      disable progress bar output
  -h, --help             help for put-file

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

list-files

List files from a service's storage provider path.

The STORAGE_PROVIDER argument follows the format STORAGE_PROVIDER_TYPE.STORAGE_PROVIDER_NAME, being the STORAGE_PROVIDER_TYPE one of the three supported storage providers (MinIO, S3 or Onedata) and the STORAGE_PROVIDER_NAME is the identifier for the provider set in the service's definition.

Usage:
  oscar-cli service list-files SERVICE_NAME STORAGE_PROVIDER REMOTE_PATH [flags]

Aliases:
  list-files, list-file, lsf

Flags:
  -c, --cluster string   set the cluster
  -h, --help             help for list-files

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

bucket

Inspect and manage OSCAR buckets to review their contents.

Subcommands

list

List the objects stored in a bucket.

Usage:
  oscar-cli bucket list BUCKET_NAME [flags]

Aliases:
  list, ls

Flags:
  -c, --cluster string   set the cluster
  -h, --help             help for list
  -o, --output string    output format (table or json) (default "table")
      --all              automatically retrieve every page of objects
      --limit int        maximum number of objects per request (defaults to server settings)
      --page string      continuation token returned by a previous call
      --prefix string    filter objects by key prefix

Global Flags:
      --config string   set the location of the config file (YAML or JSON)

interactive

Launch an interactive terminal interface to browse OSCAR clusters and services.

Usage:
  oscar-cli interactive [flags]

Aliases:
  interactive, ui

Flags:
      --config string   set the location of the config file (YAML or JSON)
  -h, --help            help for interactive

While the UI is running you can:

• Press q to quit the application.
• Press r to refresh services for the selected cluster.
• Use the arrow keys or Tab to move between clusters and services. Selecting a service shows its details in the lower pane.
• When viewing buckets, press Enter to focus the object list, use o to reload objects, n/p to page through results, and a to load every object available.

version

Print the version.

Usage:
  oscar-cli version [flags]

Aliases:
  version, v

Flags:
  -h, --help   help for version

help

Help provides help for any command in the application. Simply type oscar-cli help [path to command] for full details.

Usage:
  oscar-cli help [command] [flags]

Flags:
  -h, --help   help for help