Skip to main content
The 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:
No package manager? Download the archive for your platform from the releases page. Then check the install:
The output names two versions: the CLI release, and the API version it speaks.

Log in

On your own machine, log in through the browser:
The CLI prints a one-time code and opens an approval page. Approve it, and the CLI stores a credential in ~/.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:
Every command picks its credential in the same order, and the first one it finds wins:
  1. The --api-key flag
  2. CADENYA_API_KEY
  3. The stored login from cadenya auth login
  4. A temporary workspace in the current directory
An API key in your environment beats your stored login. So when a command acts as the wrong identity, run cadenya auth status. Its last line names the source in effect:
(The flag and 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:
Leave the flag off and you get the profile named default.

Pick a workspace

Most commands work inside one workspace, so the CLI needs to know which. List yours:
You should see (trimmed to the Development row):
Then store one as your default, by ID or by external ID:
The stored default belongs to the active profile, and workspace-id is the one key config set takes. Three more commands read it back or remove it:
The workspace resolves in order too: the --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:
Child resources nest under their parent, so tools live at 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 the metadata and spec wrappers dropped, so metadata.name is --name and spec.description is --description:
Add --dry-run to any command that sends a body, and the CLI prints the body instead of sending it:
You should see:
That output is a valid body file. Save it, then send it with -f:
A file and flags can share a command, and the flag wins:
-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:
The file still holds fields an update doesn’t accept, such as the ID and the timestamps. The CLI drops them with a warning, or fails on them when you pass --strict.

A few flag rules

  1. A boolean flag takes no separate value. --include-info turns it on and --include-info=false turns it off. (--include-info false is a usage error.)
  2. A repeatable flag takes one value each time: --names a --names b. Commas don’t split, so a value can hold one.
  3. A map takes KEY=VALUE, once per pair: --label team=support --label env=prod.
  4. A string flag takes @path to 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:
A list command prints one page. In a table, the cursor for the next page goes to stderr, so stdout stays clean for a pipe. In JSON, it’s the nextCursor field. Pass it back to keep going:
Streaming commands print one JSON event per line and nothing else:
Each line parses on its own, so 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:
Give it a command path, and it prints that command’s whole contract as markdown:
You should see (trimmed):
The contract has three parts: the positional arguments, every flag with the body field it sets and the values it allows, and a JSON Schema for each nested document the command accepts. For a command with a deep body, such as 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. The config commands read a cadenya.yaml and a .cadenya/ directory of config files, then make your workspace match them:
Three commands take that directory to your workspace:
Validate runs without a credential, so it’s cheap enough for a pre-commit hook:
Plan shows each operation before anything happens (log lines trimmed):
And apply runs the plan.
Apply deletes every resource that carries your bundle key and has no file in .cadenya/. Read every delete line in the plan before you apply.
All three run from the directory that holds 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.

Where to go next

Every command and flag is in the CLI’s command reference. To put the CLI to work on a new project, set up Cadenya from a coding agent.