cadenya CLI does everything the API does, from a terminal. Every API endpoint has a command, and a few commands exist only in the CLI: auth for logging in, schema for looking up what a command takes, and config for applying a directory of YAML to a workspace.
Install the CLI
Homebrew covers macOS and Linux. Chocolatey covers Windows:Log in
On your own machine, log in through the browser:~/.cadenya/credentials. It never prints the credential. On a machine with no browser, add --no-browser and the CLI prints the URL for you to open somewhere else.
Two more commands finish the set:
Use an API key instead
Servers and CI have no browser. Set an API key in the environment instead:- The
--api-keyflag CADENYA_API_KEY- The stored login from
cadenya auth login - A temporary workspace in the current directory
cadenya auth status. Its last line names the source in effect:
CADENYA_API_KEY are one input, so status reports both as the flag.)
Keep more than one login
A profile is a named slot for a stored login and its defaults. Pass--profile to any command, auth login included:
default.
Pick a workspace
Most commands work inside one workspace, so the CLI needs to know which. List yours:workspace-id is the one key config set takes. Three more commands read it back or remove it:
--workspace-id flag, then CADENYA_WORKSPACE_ID, then the stored default, then the one workspace your login reaches (when it reaches exactly one). So a single command can step outside your default:
Run commands
Every command is a resource, then a verb:tool-sets tools and variations at agents variations. Anywhere a command takes an ID, it also takes external_id: and your own ID. And --help works at every level: cadenya --help lists the resources, cadenya agents --help lists the verbs.
Send a request body
Every scalar field in a request body is a flag. The flag’s name is the field’s path with themetadata and spec wrappers dropped, so metadata.name is --name and spec.description is --description:
--dry-run to any command that sends a body, and the CLI prints the body instead of sending it:
-f:
-f takes YAML or JSON, and -f - reads the body from stdin. The same trick edits a resource in place. Pull it down as YAML, change what you need, and send it back:
--strict.
A few flag rules
- A boolean flag takes no separate value.
--include-infoturns it on and--include-info=falseturns it off. (--include-info falseis a usage error.) - A repeatable flag takes one value each time:
--names a --names b. Commas don’t split, so a value can hold one. - A map takes
KEY=VALUE, once per pair:--label team=support --label env=prod. - A string flag takes
@pathto read a file, or-to read stdin. That keeps secrets out of your shell history.
Read the output
Most commands print a table. Pick another shape with--display, on one command or on cadenya itself:
A table shows a few columns.
json and yaml print the whole resource, so use those in scripts:
nextCursor field. Pass it back to keep going:
jq -c and while read both work. Press Ctrl-C to stop watching. After a dropped connection, pass --last-event-id to pick up where the stream stopped. The objectives guide covers what the events mean.
Exit codes
When a request fails and the message isn’t enough, add
--debug. The CLI dumps every HTTP exchange to stderr, with credentials redacted.
Get a command’s schema
cadenya schema prints what a command takes: its arguments, its flags, and the shape of its body. With no arguments, it lists every resource command with a one-line summary:
agents variations create, that last part is the one you want.
Point your coding agent at cadenya schema before it builds a request. The contract names every flag and every allowed value, so the agent has nothing to guess. The command runs offline, so it works before you log in.
schema covers the resource commands. For auth, config, and whoami, use --help.
Apply config from a directory
For a whole setup, keep the resources in files. Theconfig commands read a cadenya.yaml and a .cadenya/ directory of config files, then make your workspace match them:
cadenya.yaml. A few flags change where they look and what they print:
This section covers the commands. Config files covers what goes in the directory: the file format, the bundle key rules, and the GitHub Action that runs these commands on every push.