> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the cadenya CLI, log in, run commands against your workspace, look up any command's schema, and apply a directory of config files.

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:

```bash Homebrew theme={null}
brew install cadenya/tools/cadenya
```

```powershell Chocolatey theme={null}
choco install cadenya
```

```bash Go theme={null}
go install go.cadenya.com/cadenya-cli@latest
```

No package manager? Download the archive for your platform from the [releases page](https://github.com/cadenya/cadenya-cli/releases). Then check the install:

```bash theme={null}
cadenya --version
```

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:

```bash theme={null}
cadenya auth login
```

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:

```bash theme={null}
cadenya auth status   # who's logged in, and which credential commands use
cadenya auth logout   # delete the stored credential
```

### Use an API key instead

Servers and CI have no browser. Set an [API key](https://cadenya.com/docs/api-keys.md) in the environment instead:

```bash theme={null}
export CADENYA_API_KEY=your-api-key
```

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](https://cadenya.com/docs/setup-from-a-coding-agent.md#temporary-workspace-rules) 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:

```
Profile "default": logged in.
  workspace: workspace_01KZ950VTH0TJ2ZKF503VX1QPN
Credential source: --api-key flag.
```

(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:

```bash theme={null}
cadenya --profile staging auth login
cadenya --profile staging agents list
```

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:

```bash theme={null}
cadenya workspaces list
```

You should see (trimmed to the Development row):

```
ID                                    EXTERNAL ID  NAME         CREATED
workspace_01KZ950VTH0TJ2ZKF503VX1QPN  development  Development  -
```

Then store one as your default, by ID or by external ID:

```bash theme={null}
cadenya config set workspace-id development
```

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:

```bash theme={null}
cadenya config get workspace-id     # the stored default, empty if unset
cadenya config list                 # the value in effect, and where it comes from
cadenya config unset workspace-id   # remove the stored default
```

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:

```bash theme={null}
cadenya agents list --workspace-id production
```

## Run commands

Every command is a resource, then a verb:

```bash theme={null}
cadenya agents list
cadenya agents retrieve external_id:petstore-agent
cadenya tool-sets tools list external_id:petstore
```

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`:

```bash theme={null}
cadenya agents create \
  --name "Petstore Agent" \
  --external-id petstore-agent \
  --description "Answers questions about pets in the Swagger Petstore"
```

Add `--dry-run` to any command that sends a body, and the CLI prints the body instead of sending it:

```bash theme={null}
cadenya agents create \
  --name "Petstore Agent" \
  --external-id petstore-agent \
  --description "Answers questions about pets in the Swagger Petstore" \
  --dry-run
```

You should see:

```yaml theme={null}
metadata:
  externalId: petstore-agent
  name: Petstore Agent
spec:
  description: Answers questions about pets in the Swagger Petstore
```

That output is a valid body file. Save it, then send it with `-f`:

```bash theme={null}
cadenya agents create -f agent.yaml
```

A file and flags can share a command, and the flag wins:

```bash theme={null}
cadenya agents create -f agent.yaml --name "Petstore Agent (staging)"
```

`-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:

```bash theme={null}
cadenya agents retrieve external_id:petstore-agent --display yaml > agent.yaml
cadenya agents update external_id:petstore-agent -f agent.yaml
```

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:

| Mode | Prints |
| - | - |
| `table` | Aligned columns, one row per resource. The default for most commands. |
| `extended` | The same columns as vertical records, one field per line. |
| `json` | The full response as indented JSON. |
| `yaml` | The full response as YAML. Pairs with `-f`. |

A table shows a few columns. `json` and `yaml` print the whole resource, so use those in scripts:

```bash theme={null}
cadenya workspaces list --display json \
  | jq -r '.items[] | select(.metadata.externalId == "development") | .metadata.id'
```

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:

```bash theme={null}
cadenya agents list --limit 50 --cursor <next-cursor>
```

Streaming commands print one JSON event per line and nothing else:

```bash theme={null}
cadenya objectives stream-events obj_01M11M39G1AND50FXH9P39ZSR2
```

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](https://cadenya.com/docs/guides/the-basics/objectives.md) covers what the events mean.

### Exit codes

| Code | Meaning |
| - | - |
| `0` | Success. |
| `1` | The API or the network returned an error. The message is on stderr. |
| `2` | A usage error, such as a missing argument. The CLI sent nothing. |
| `130` | Interrupted, such as Ctrl-C on a stream. |

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:

```bash theme={null}
cadenya schema
```

Give it a command path, and it prints that command's whole contract as markdown:

```bash theme={null}
cadenya schema agents list
```

You should see (trimmed):

````markdown theme={null}
# cadenya agents list

List agents

```sh
cadenya agents list [--workspace-id <value>] [--limit <value>] [--cursor <value>] [--prefix <value>] [--query <value>] [--state <value>] [--variation-selection-mode <value>] [--labels <value>] [--sort-order <value>] [--include-info[=true|false]]
```

## Flags

- `[--workspace-id <value>]` — Workspace ID.
- `[--limit <value>]` — Maximum number of results to return
- `[--cursor <value>]` — Pagination cursor from previous response
````

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](https://cadenya.com/docs/config-files.md), then make your workspace match them:

```text theme={null}
cadenya.yaml
.cadenya/
  toolSets/
    petstore.yaml
  agents/
    petstore-agent.yaml
    petstore-agent/
      default.yaml
```

Three commands take that directory to your workspace:

```bash theme={null}
cadenya config validate   # offline: YAML, fields, and references
cadenya config plan       # reads the workspace, changes nothing
cadenya config apply      # deletes what's missing, then creates and updates
```

Validate runs without a credential, so it's cheap enough for a pre-commit hook:

```
Valid bundle petstore-app: 3 resources
```

Plan shows each operation before anything happens (log lines trimmed):

```
create    toolSet petstore
create    agent petstore-agent
create    agentVariation petstore-agent/default
publish   agent petstore-agent
Plan: 3 create, 0 update, 0 delete, 0 detach, 1 state change
```

And apply runs the plan.

> [!WARNING]
>
> 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:

| Flag | Does |
| - | - |
| `-C`, `--directory` | Points at another directory: `cadenya config plan -C path/to/repo`. |
| `--resource-dir` | Names the resource directory, when it isn't `.cadenya`. |
| `--bundle-key` | Overrides the `bundleKey` in `cadenya.yaml`. So does `CADENYA_BUNDLE_KEY`. |
| `--output json` | Prints the result as one JSON document, for a script to read. |
| `--report-file` | Writes that JSON result to a file, failures included. |
| `--allow-empty` | Lets apply delete the whole bundle when `.cadenya/` is empty. Without it, apply refuses an empty directory. |

This section covers the commands. [Config files](https://cadenya.com/docs/config-files.md) 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](https://github.com/cadenya/cadenya-cli/blob/main/api.md). To put the CLI to work on a new project, [set up Cadenya from a coding agent](https://cadenya.com/docs/setup-from-a-coding-agent.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.