unkey api command accepts these five flags on top of its own. Four of them can also be set with an environment variable, which is the usual way in CI.
string
Root key used for the request. Falls back to
UNKEY_ROOT_KEY, then to the config file. See CLI authentication.string
default:"https://api.unkey.com"
Base URL of the API. Falls back to
UNKEY_API_BASE_URL. You don’t normally need to set it.string
default:"~/.unkey/config.toml"
Path of the TOML config file that
unkey api commands read the root key from. Falls back to UNKEY_CONFIG. unkey auth login always writes ~/.unkey/config.toml, so only point this elsewhere if you write that other file yourself.string
Output format. Falls back to
UNKEY_OUTPUT. Set it to json for the full response. Any other value gives the default layout. See Output formats.string
A JSON request body to send instead of building one from the command’s flags. See Send a raw body.
Output formats
By default a successful command prints the request ID, a blank line, and then the response’sdata as indented JSON:
--output=json, the CLI prints the whole response, meta and data, exactly as the API returned it. Use this when you pipe into jq or another tool, because the default layout mixes a plain-text line with JSON:
UNKEY_OUTPUT=json once in a script to do the same for every command.
Send a raw body
Normally a command builds its request from its flags, one per request field, and checks them before sending. If you already have the request as JSON, for example from a file or another tool, pass it with--body instead:
--body:
- It must be one JSON object that matches the endpoint’s request.
- Unknown fields fail before anything is sent, so a typo in a field name doesn’t get silently ignored.
- You can’t combine it with the command’s request flags. Required flags aren’t needed either, so
keys create-key --body='...'doesn’t also need--api-id. - The five shared flags above still work.
Errors and exit codes
A failed command prints one message and exits with status 1. API errors are shortened:
Other failures print the error text as is. Help and version requests (
--help, -h, help <command>, --version) exit 0 without calling the API.
Flag syntax
--api-id=api_123 and --api-id api_123 are the same. A boolean flag on its own (--enabled) means true, and you can write --enabled=false. Flags can go before or after positional arguments. An unknown flag fails right away, and the message lists the flags the command accepts.