NOVA CLI reference 0.5.0 GitHub
  1. nova

nova api

Send an authenticated request to the NOVA API of the instance

Synopsis

Send an authenticated request to the instance and print the answer, like 'gh api'.

The path is the complete path on the instance, starting with '/': the NOVA API v2 lives under /api/v2, other paths (apps, NovaFlow) work as well. {cell} is replaced by the cell of the instance; fill in other placeholders yourself. Host and credentials come from the targeted instance (--instance, NOVA_INSTANCE or 'nova instance select'); credentials are never sent to another host.

Find operations with 'nova api search <words>' and their parameters and body with 'nova api schema <operationId>' (both read the instance's v2 spec, cached per NOVA version under ~/.nova/cache/api). Try a request with --dry-run first.

The answer goes to stdout as the instance sends it; with an HTTP error status the body is still printed and nova exits with 1. Binary answers (archives, models) need --output.

Fields: -f key=value string field -F key=value typed field: true, false, null and numbers become JSON literals, @file (or @- for stdin) reads the value from a file Nested keys like gh: pose[position][]=1 or items[][name]=a. Fields make the request a POST unless -X is given; with GET (or together with --input) they go to the query. --input file the request body from a file (- for stdin)

The answer is printed as it arrives, so long polls (e.g. waitForIOEvent, with a longer --timeout or --timeout 0) work. WebSocket streams (state streams, jogging, trajectory execution) are refused with STREAM_NOT_SUPPORTED (exit 3): nova api speaks plain HTTP.

nova api has no guard rails: it can do what the instance's credentials allow, including moving robots. Point it at an instance with real robots only when someone is at the cell.

nova api <path> [flags]

Examples

  nova api /api/v2/cells/{cell}/controllers
  nova api /api/v2/cells/{cell}/controllers/ur5 --include
  nova api /api/v2/cells/{cell}/store/objects/my-key -X PUT --input data.json
  nova api /api/v2/cells/{cell}/controllers/ur5/ios/values -X PUT --input outputs.json --dry-run
  nova api /api/v2/system/diagnosis-package/zip --output diagnosis.zip
  nova api search "inverse kinematics"
  nova api schema inverseKinematics

Options

      --dry-run               Check and print the request as JSON without sending it
  -F, --field key=value       Add a typed field key=value (true, false, null, numbers, @file)
  -H, --header stringArray    Add a request header 'Key: value'
  -h, --help                  help for api
  -i, --include               Print the status line and response headers before the body
      --input string          Read the request body from a file (- for stdin)
  -X, --method string         HTTP method (default: GET, or POST with fields or --input)
  -o, --output string         Write the response body to a file (needed for binary answers)
  -f, --raw-field key=value   Add a string field key=value
      --silent                Don't print the response body
      --timeout duration      How long to wait for the answer's headers and for the API spec (0: no limit for the answer) (default 1m0s)

Options inherited from parent commands

      --debug                      Write diagnostic output to stderr: HTTP requests and responses, external commands, the resolved instance. Known secrets are redacted, but bodies (app environments, kubeconfigs) can still contain some: don't share the output unreviewed (env: NOVA_DEBUG=1)
      --env string                 (Wandelbots internal) Portal environment for this invocation: prod, stg or dev (default: the environment of the cloud instance, else of the last 'nova login'; env: NOVA_ENV)
      --insecure-skip-tls-verify   If true, the server's certificate will not be checked for validity (disables TLS verification for all requests)
      --instance string            Name of the instance to work against for this invocation (overrides the selected instance; env: NOVA_INSTANCE)

SEE ALSO

  • nova - CLI for interacting with Wandelbots NOVA OS
  • nova api schema - Show parameters and request body of an operation
  • nova api search - Find operations of the instance's NOVA API v2