---
name: reindeer-external-cli
description: >
  Use the public Reindeer CLI to manage workspaces, agents, runs, cases,
  evaluations, connectors, artifacts, contexts, extensions, notifications,
  interactions, feedback, operations, members, and service accounts.
  Trigger for Reindeer CLI setup, workspace administration, agent execution,
  connector operations, case investigation, dynamic UI, or public API discovery.
---

# Reindeer CLI

Use the public `reindeer` binary for customer-facing Reindeer operations.

## Operating rules

- Run `reindeer <resource> --help` and `reindeer <resource> <verb> --help` before
  constructing an unfamiliar command. CLI help and the tenant OpenAPI schema are
  authoritative; resource schemas evolve.
- Pass `-w <workspace>` for workspace-scoped resources. Names and IDs are both
  accepted where help says "ID or name."
- Use `-o json` for programmatic output. List responses include pagination
  metadata; follow `next_page_token` when present.
- Prefer full AIP-122 resource names inside JSON bodies, for example
  `workspaces/<workspace>/agents/<agent>/runs/<run>`.
- Treat secret values, OAuth client secrets, and artifact download URLs as
  sensitive. Do not print or persist them unnecessarily.
- Use `--wait` when available. Otherwise poll the returned operation until
  `done` is `true`.

## Install and authenticate

Install on macOS or Linux:

```bash
curl -fsSL https://headless.reindeerlabs.ai/install.sh | bash
reindeer --version
reindeer login
```

Install on Windows:

```powershell
irm https://headless.reindeerlabs.ai/install.ps1 | iex
reindeer --version
reindeer login
```

For a non-interactive agent, use both flags and surface the printed URL to the
user:

```bash
reindeer login --headless --no-prompt
```

Target another tenant or saved profile consistently:

```bash
reindeer login --headless --no-prompt \
  --profile demo \
  --base-url https://api.demo.reindeerlabs.ai

reindeer -p demo -b https://api.demo.reindeerlabs.ai -w <workspace> agents list
```

Useful global flags:

| Flag | Purpose |
|---|---|
| `-w, --workspace <name>` | Workspace name or ID |
| `-o, --output json\|table` | Output format |
| `-b, --base-url <url>` | API base URL override |
| `-p, --profile <name>` | Configuration profile |
| `-v, --verbose` | Verbose logging |

Inspect or diagnose local configuration:

```bash
reindeer config list
reindeer config profiles
reindeer doctor
```

## Discover commands and schemas

Start with CLI help:

```bash
reindeer --help
reindeer <resource> --help
reindeer <resource> <verb> --help
```

The public tenant schema is available without authentication:

- OpenAPI: `https://api.<tenant>.reindeerlabs.ai/api/v1/openapi.json`
- Swagger UI: `https://api.<tenant>.reindeerlabs.ai/api/v1/docs`

Use these resource groups:

| Resource | Main verbs |
|---|---|
| `workspaces` | `list`, `get`, `create`, `update`, `delete` |
| `templates` | `list`, `get` |
| `connection-profiles` | `list`, `get`, `create`, `update`, `delete`, `test` |
| `connectors` | `list`, `get`, `create`, `update`, `delete`, `trigger` |
| `artifacts` | `list`, `get`, `create`, `download` |
| `contexts` | CRUD, `versions`, `version`, `new-version` |
| `agents` | `list`, `get`, `create`, `update`, `delete` |
| `agent-revisions` | `list`, `get` |
| `evaluations` | `list`, `get`, `create` |
| `runs` | `list`, `get`, `create` |
| `steps` | `list`, `get` |
| `cases` | `list`, `get`, `update`, `delete`, `search`, `aggregate`, `history` |
| `interactions` | `inbox`, `list`, `get`, `respond` |
| `feedback` | `list`, `create` |
| `extensions` | CRUD, `versions`, `version`, `new-version` |
| `notifications` | `list`, `get`, `create`, `update`, `delete` |
| `secrets` | `list`, `get`, `create`, `update`, `delete` |
| `operations` | `list`, `get` |
| `members` | `list`, `invite`, `update-role`, `remove` |
| `workspace-members` | `list`, `update` |
| `service-accounts` | CRUD, `rotate-secret` |

## Long-running operations

Mutations and interaction responses may return an operation:

```bash
reindeer operations get <operation-id> -w <workspace> -o json
```

A completed operation has `done: true` and either `result` or `error`. An
operation that creates a run completes before the run itself; then poll
`reindeer runs get`.

## Connection profiles and connectors

Connection profiles hold connector authentication. Use the command-specific
help or OpenAPI schema for the selected `connection_profile_type`.

```bash
reindeer connection-profiles create -w <workspace> --data '{
  "connection_profile_id": "<id>",
  "display_name": "<name>",
  "connection_profile_type": "<type>",
  "config": {}
}'
reindeer connection-profiles test <profile> -w <workspace>
```

Create and trigger an API connector:

```bash
reindeer connectors create -w <workspace> --data '{
  "connector_id": "file-upload",
  "display_name": "File Upload",
  "connector_type": "api",
  "config": {"connector_type":"api","trigger_mode":"per_file"}
}'

reindeer connectors trigger <connector> -w <workspace> --file <path>
```

Pass multiple `--file` flags for multiple files.

## Artifacts

Create a document artifact:

```bash
reindeer artifacts create -w <workspace> --file <path> --data '{
  "artifact_type": "document",
  "unique_key": "<dedup-key>",
  "data": "{\"type\":\"document\",\"filename\":\"<filename>\",\"content_type\":\"<mime>\",\"size_bytes\":0}"
}'
```

`data` is a JSON-encoded string, not a nested object. Downloading returns a
short-lived signed URL:

```bash
reindeer artifacts download <artifact-id> -w <workspace> -o json
```

## Contexts and agents

Before writing, restructuring, or reviewing Context artifacts, read
[Writing Effective Context for Reindeer Agents](references/writing-effective-contexts.md).
Use it to separate system-prompt controls, operating policy, schemas, and
reference data; preserve one canonical owner per rule; and review for narrative,
slop, and conflicting rules. For retrieval-only or routine CLI operations, the
commands below are sufficient.

Context entries reference artifacts by full resource name:

```bash
reindeer contexts create -w <workspace> \
  --name <name> \
  --display-name "<display name>" \
  --entries '[{"artifact":"workspaces/<workspace>/artifacts/<artifact-id>","display_name":"<entry>","description":"<description>"}]'

reindeer contexts new-version <context> -w <workspace> \
  --entries '[{"artifact":"workspaces/<workspace>/artifacts/<artifact-id>","display_name":"<entry>","description":"<description>"}]'
```

A new context version can trigger compilation of a new agent revision.

Create an agent with a connector subscription and context:

```bash
reindeer agents create -w <workspace> \
  --name <name> \
  --display-name "<display name>" \
  --subscriptions '{"connector_type":"api","connector":"workspaces/<workspace>/connectors/<connector>","events":[{"type":"api_trigger"}]}' \
  --contexts workspaces/<workspace>/contexts/<context>
```

Pass each subscription as a separate `--subscriptions` value.

## Runs, steps, and cases

Create a run with `--input`. The required `type` is `new_run`,
`previous_run`, or `previous_case`.

```bash
reindeer runs create -w <workspace> --agent <agent> --wait \
  --input '{"type":"new_run","user_input":"<instruction>","artifacts":[]}'
```

Resume a run session:

```bash
reindeer runs create -w <workspace> --agent <agent> --input '{
  "type":"previous_run",
  "previous_run":"workspaces/<workspace>/agents/<agent>/runs/<run>",
  "session":{"session":"resume","user_input":"<follow-up>"}
}'
```

For `previous_run` and `previous_case`, `session` is a nested object. Use
`"session":"new"` for a fresh session linked to the prior input. Poll the run
until its status is no longer `running`.

Inspect related execution data:

```bash
reindeer steps list -w <workspace> --agent <agent> --run-id <run>
reindeer cases list -w <workspace> --agent <agent>
reindeer cases search -w <workspace> --agent <agent> --text "<text>"
reindeer cases aggregate -w <workspace> --agent <agent> --group-by <field>
reindeer cases history <case> -w <workspace> --agent <agent>
```

Check each case subcommand's help for filters, pagination, and aggregation
options.

## Evaluations

Evaluate a revision against its latest golden dataset, or pass full case
resource names explicitly. Evaluation commands require CLI 0.3.32 or newer.

```bash
reindeer evaluations list -w <workspace> --agent <agent>
reindeer evaluations list -w <workspace> --agent <agent> --revision <revision>
reindeer evaluations get -w <workspace> --agent <agent> <evaluation-resource-name>
reindeer evaluations create -w <workspace> --agent <agent> \
  --revision <revision> --wait
reindeer evaluations create -w <workspace> --agent <agent> \
  --revision <revision> \
  --cases workspaces/<workspace>/agents/<agent>/cases/<case-1> \
          workspaces/<workspace>/agents/<agent>/cases/<case-2>
```

`create` always requires `--revision`. For `get`, a full evaluation resource
name carries its revision; with a bare evaluation ID, also pass `--revision`.
Use `get` for per-case scores and the criteria rollup; `list` is a summary.

## Interactions and feedback

Find pending human-in-the-loop requests and respond:

```bash
reindeer interactions inbox -w <workspace> --agent <agent> --status pending
reindeer interactions respond <interaction> -w <workspace> \
  --agent <agent> --run-id <run> --text "<answer>"
reindeer interactions respond <interaction> -w <workspace> \
  --agent <agent> --run-id <run> --decision allow --note "<optional note>"
```

Use `--selected <label...>` for option labels. A `409` means the interaction
is no longer pending.

Create textual feedback for a run, step, or case:

```bash
reindeer feedback create -w <workspace> --agent <agent> --data '{
  "feedback_context":{"type":"run_feedback","run":"workspaces/<workspace>/agents/<agent>/runs/<run>"},
  "feedback_data":{"type":"textual","sentiment":"positive","text":"<feedback>"}
}'
```

## Notifications

Notifications deliver platform events through a connection profile:

```bash
reindeer notifications create -w <workspace> --wait \
  --name run-done \
  --display-name "Run complete" \
  --events run_completion \
  --connection-profile <profile> \
  --scope '{"type":"workspace"}' \
  --enabled true
```

Use `update --enabled false` to pause delivery.

## Extensions and dynamic UI

Extensions are versioned display surfaces. Treat `ExtensionType`,
`ExtensionPayload`, and the dynamic UI component schema in the tenant OpenAPI
document as authoritative.

```bash
reindeer extensions create -w <workspace> --wait \
  --name <name> \
  --type <type> \
  --parent workspaces/<workspace>/agents/<agent> \
  --display-name "<display name>" \
  --payload '{"type":"<type>","view_spec":{}}'

reindeer extensions new-version <extension> -w <workspace> \
  --payload '{"type":"<type>","view_spec":{}}'
```

`update` changes mutable metadata; `new-version` replaces the served payload.

For `display_case_decision` and `display_case_decision_outlook`, render data is
`{case, artifacts: {input}}`. Read case state from `/case/state/...`, read input
artifact references from `/artifacts/input`, and keep editable write paths
relative to `case.state` (for example, read `/case/state/status` but write
`/status`). `DocumentPreview.fieldsPath` must bind to the resolved fields array,
not a plain path string. Do not add a top-level `view_spec.state`.

## Secrets, members, and service accounts

Secret values are write-only:

```bash
reindeer secrets create -w <workspace> \
  --name <name> --description "<description>" --value "<value>"
```

Organization and workspace access:

```bash
reindeer members list
reindeer members invite --email <email> --org-role <role>
reindeer workspace-members list -w <workspace>
reindeer workspace-members update <member-id> -w <workspace> --role <role>
```

Service accounts are organization-scoped OAuth clients:

```bash
reindeer service-accounts create \
  --display-name "<name>" \
  --org-role organization_viewer \
  --workspace-roles '{"<workspace>":"workspace_editor"}'
reindeer service-accounts rotate-secret <service-account>
```

Create and rotate return the client secret once. Capture it securely; list and
get never return it.

## Keep the CLI and skill current

```bash
reindeer upgrade
reindeer install-skill
```

`install-skill` offers detected Claude Code, Codex, and GitHub Copilot
installations, lets the user choose user or project scope, and delegates skill
placement to `gh skill install`. For a non-interactive update, use:

```bash
reindeer install-skill --agent <claude|codex|copilot> --scope user --yes
```