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