> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Runtype CLI reference

> Install, sign in to, and update the runtype CLI, and look up the commands for flows, agents, records, secrets, schedules, surfaces, evals, products, and logs.

The `runtype` CLI manages the resources in your Runtype account from a terminal. This page lists how to install and authenticate the CLI, the options that every command accepts, and the commands in each command group. For the full list of options for any command, run it with `--help`:

```bash
runtype flows run --help
```

## Install

The CLI is the `@runtypelabs/cli` npm package and requires Node.js 22.12.0 or later. Install it globally with the following command:

```bash
npm install -g @runtypelabs/cli
```

To run a single command without installing the package, replace `runtype` with `npx @runtypelabs/cli@latest`:

```bash
npx @runtypelabs/cli@latest agents list
```

To sign in, install Runtype agent skills, and connect a coding agent in one step, run `runtype onboard`. For more information, see [Connect Runtype to coding agents](/developer-guides/integrations/connect-coding-agents).

## Update

A global installation checks npm for a new stable release once per hour. When it finds one, it downloads and verifies the release in the background and uses it on the next invocation. Automatic updates are off in CI (when the `CI` environment variable is set), for `npx` runs, and for project-local installations.

The `runtype update` command checks for and installs updates on demand:

| Command                     | Result                                                                      |
| --------------------------- | --------------------------------------------------------------------------- |
| `runtype update`            | Installs the newest stable release. It takes effect on the next invocation. |
| `runtype update --check`    | Reports whether an update is available, without installing it.              |
| `runtype update --rollback` | Returns to the previously active version.                                   |

The following environment variables control automatic updates:

* `RUNTYPE_DISABLE_AUTO_UPDATE=true`: keeps the version that your package manager installed, including a pinned version.
* `RUNTYPE_DISABLE_UPDATE_CHECK=true`: keeps the active version and stops the hourly check.

## Authenticate

Every command that calls the Runtype API needs a credential. The CLI uses the first one that it finds, in the following order:

1. The `RUNTYPE_API_KEY` environment variable.
2. A login that `runtype login` stored. The CLI keeps one login for each organization and picks one as described in [Use several organizations](#use-several-organizations).
3. Browser sign-in, when the terminal is interactive.

`runtype login` stores the API key in the operating system keychain: Keychain on macOS, Credential Manager on Windows, or the Secret Service on Linux. When no keychain is available, such as in a container, the CLI stores the key in an encrypted file in `~/.runtype`. To choose the store, set `RUNTYPE_CREDENTIAL_STORE` to `keychain` or `file`.

The following commands manage stored logins:

| Command                             | Description                                                                                                               |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `runtype login`                     | Opens the browser to sign in and stores an API key for the organization that you authorize. Same as `runtype auth login`. |
| `runtype login --api-key <api-key>` | Stores an API key without a browser. Use this form in CI and other noninteractive shells.                                 |
| `runtype auth signup`               | Opens the browser sign-in page, which links to account creation.                                                          |
| `runtype auth status`               | Shows which login the current directory uses, and why.                                                                    |
| `runtype auth accounts`             | Lists the stored logins.                                                                                                  |
| `runtype auth switch [<org-id>]`    | Sets the default login for directories without a project link.                                                            |
| `runtype auth whoami`               | Shows the signed-in user and organization.                                                                                |
| `runtype auth export-key`           | Prints the API key of the login that the current directory uses, with no other output.                                    |
| `runtype auth logout [<org-id>]`    | Removes the login that the current directory uses, or the login for `<org-id>`. Add `--all` to remove every login.        |
| `runtype link [<org-id>]`           | Links the current directory to an organization. See [Use several organizations](#use-several-organizations).              |
| `runtype unlink`                    | Removes the nearest project link.                                                                                         |

Replace `<api-key>` with an API key from **Settings > API** in the dashboard. For more information, see [Managing API keys](/user-guide/settings/managing-api-keys).

To pass the stored key to another tool, capture the output of `runtype auth export-key`:

```bash
export RUNTYPE_API_KEY="$(runtype auth export-key)"
```

Browser sign-in needs an interactive terminal. Without one, the CLI prints the next command to run instead of opening a browser. A coding agent can also register an account without a browser with `runtype auth register`. For that flow, see [Authentication](/developer-guides/getting-started/authentication#agent-self-registration-anonymous-start).

## Use several organizations

You can stay logged in to several organizations at the same time. Each `runtype login` adds a login for the organization that you authorize on the sign-in page. Logging in to an organization again replaces its earlier login.

The CLI picks the login for a command from the first of the following that is set:

1. The `--org <org-id>` option.
2. The `RUNTYPE_ORG` environment variable.
3. The nearest `.runtype/project.json` file in the current directory or a parent directory.
4. The default login. The most recent `runtype login` outside a linked project sets it, and `runtype auth switch` changes it.

To make every command in a project use one organization, run `runtype link` in the project root:

```bash
runtype link <org-id>
```

The command writes `.runtype/project.json`. The file contains the organization ID and, for a non-production Runtype API such as staging, the API URL. A link can only pin a Runtype API host; to use any other host, pass `--api-url` or set `RUNTYPE_API_URL`. It contains no secrets, so commit it to share the setting with your team. Each person still logs in with their own account.

If a project is linked to an organization that you have no login for, the CLI stops and asks you to log in. It never uses a login for another organization. `runtype login` in that directory opens the sign-in page with the linked organization selected.

## Global options

The following options apply to every command:

| Option                   | Description                                                                                                                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`                 | Prints the result as JSON instead of formatted text.                                                                                                  |
| `--no-input`             | Turns off prompts and browser sign-in. A `delete`, `bulk-delete`, `revoke`, or `reset` command then also requires `--yes`.                            |
| `-y`, `--yes`            | Confirms a destructive command in `--no-input` mode.                                                                                                  |
| `--api-url <url>`        | Sends requests to a different Runtype API base URL, such as a self-hosted deployment. The `RUNTYPE_API_URL` environment variable sets the same value. |
| `--org <org-id>`         | Uses the stored login for the organization `<org-id>`. This option overrides `RUNTYPE_ORG` and `.runtype/project.json`.                               |
| `--expect-api-url <url>` | Stops the command unless the resolved API URL matches `<url>`.                                                                                        |
| `--expect-org <org-id>`  | Stops the command unless the credential belongs to the organization `<org-id>`.                                                                       |
| `-v`, `--verbose`        | Prints more detail.                                                                                                                                   |

Commands that list resources return one page at a time. To get the next page, pass the cursor from the previous result with `--cursor <cursor>`.

## Run flows and agents

The `runtype dispatch` command runs a flow or an agent and streams the response to the terminal. Pass exactly one of `--flow` and `--agent`. The following command runs a flow with two input variables and a message:

```bash
runtype dispatch --flow <flow-id> \
  --variable customerName=Dana \
  --variable priority=high \
  --message "Where is my order?"
```

Replace `<flow-id>` with the ID of the flow to run.

The following options control the input and output of `dispatch`, `flows run`, and `agents execute`:

| Option                   | Description                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `-m`, `--message <text>` | Sends a user message.                                                              |
| `--variable <key=value>` | Sets one string input variable. Repeat the option for more variables.              |
| `--inputs <json>`        | Sets typed input variables from a JSON object.                                     |
| `--inputs-file <file>`   | Reads input variables from a JSON object file. Use `-` to read stdin.              |
| `--messages-file <file>` | Reads a conversation from a JSON array of messages. Use `-` to read stdin.         |
| `--no-stream`            | Waits for the complete response instead of streaming it.                           |
| `--json`                 | Prints one final JSON result.                                                      |
| `--jsonl`                | Prints each stream event as a JSON line, followed by an `execution_summary` event. |

> **Note**
>
> Use the long form `--variable`. The short form `-v` is read as the global `--verbose` option, and the command fails with `too many arguments`.

`runtype dispatch` also accepts the following options:

| Option                       | Description                                                                |
| ---------------------------- | -------------------------------------------------------------------------- |
| `-f`, `--flow <flow-id>`     | The flow to run.                                                           |
| `-a`, `--agent <agent-id>`   | The agent to run.                                                          |
| `--alias <alias>`            | Runs the agent version that a release alias points to. Requires `--agent`. |
| `--version-id <version-id>`  | Runs one exact agent version. Requires `--agent`.                          |
| `-r`, `--record <record-id>` | Runs against an existing record.                                           |
| `--record-json <file>`       | Runs against record data from a JSON file. Use `-` to read stdin.          |
| `--debug`                    | Prints step-level details.                                                 |

## View logs

The `runtype tail` command streams live execution logs until you press Control+C. It reconnects when the stream ends. The following command streams errors for one flow:

```bash
runtype tail --flow <flow-id> --level error
```

`runtype tail` accepts `--flow`, `--agent`, `--surface`, and `--execution` to filter by ID. It also accepts `--level` (`debug`, `info`, `warn`, or `error`) and `--category` (`execution`, `agent`, `tool`, `model`, `system`, or `error`). With `--json`, it prints one JSON object per line.

The `runtype logs` commands query stored logs. Both default to the last 24 hours:

* `runtype logs list`: returns matching log entries, newest first. `--limit` sets the page size, from the default of 500 up to 1,000. `--order asc` returns the oldest first.
* `runtype logs stats`: returns totals, counts by level and category, and a histogram.

Both commands accept the following filters:

| Option                                                            | Description                                                                       |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `--from <time>`, `--to <time>`                                    | The time range, as ISO 8601 timestamps.                                           |
| `--level <levels>`                                                | Comma-separated levels.                                                           |
| `--category <categories>`                                         | Comma-separated categories.                                                       |
| `--type <types>`                                                  | Comma-separated entry types, such as `flow`, `step`, `tool`, `agent`, or `model`. |
| `--status <statuses>`                                             | Comma-separated statuses, such as `completed` or `failed`.                        |
| `--search <text>`                                                 | Matches text in an entry's message, name, operation, tool name, or error class.   |
| `--flow`, `--agent`, `--execution`, `--surface`, `--conversation` | Filters by the ID of that resource.                                               |

The following command lists failed flow runs from one day:

```bash
runtype logs list --status failed --type flow \
  --from 2027-01-19T00:00:00Z --to 2027-01-20T00:00:00Z
```

For more information, see [Working with logs](/user-guide/logs/working-with-logs).

## Flows

The `runtype flows` commands manage flows:

| Command                              | Description                                                                                                              |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `runtype flows list`                 | Lists flows. Accepts `--limit` and `--cursor`.                                                                           |
| `runtype flows get <flow-id>`        | Shows one flow.                                                                                                          |
| `runtype flows create --name <name>` | Creates a flow. `--description` sets its description. `--from-file <file>` imports the flow definition from a JSON file. |
| `runtype flows update <flow-id>`     | Updates a flow. Accepts `--name`, `--description`, or `--from-file <file>` with the full flow body.                      |
| `runtype flows delete <flow-id>`     | Deletes a flow.                                                                                                          |
| `runtype flows run <flow-id>`        | Runs a flow. Accepts the options in [Run flows and agents](#run-flows-and-agents).                                       |
| `runtype flows ensure <file>`        | Creates or updates a flow from a JSON definition file. See [Ensure flags](#ensure-flags).                                |
| `runtype flows pull <name>`          | Prints a flow as the JSON file that `ensure` reads. `-o <file>` writes it to a file.                                     |

The `runtype flow-versions` commands (`list`, `get`, `published`, and `publish`) manage the saved versions of a flow.

## Agents

The `runtype agents` commands manage agents:

| Command                                      | Description                                                                                                                                                       |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runtype agents list`                        | Lists agents, 20 at a time by default. Accepts `--limit` and `--cursor`.                                                                                          |
| `runtype agents get <agent-id>`              | Shows one agent.                                                                                                                                                  |
| `runtype agents create --name <name>`        | Creates an agent. `--description` sets its description.                                                                                                           |
| `runtype agents update <agent-id>`           | Updates an agent. Accepts `--name`, `--description`, or `--from-file <file>` with the full agent body.                                                            |
| `runtype agents delete <agent-id>`           | Deletes an agent.                                                                                                                                                 |
| `runtype agents execute <agent-id>`          | Runs an agent. Requires `--message` or `--messages-file`. Accepts `--alias` and `--version-id`, and the options in [Run flows and agents](#run-flows-and-agents). |
| `runtype agents ensure`                      | Creates or updates an agent from a JSON definition file, and can deploy it.                                                                                       |
| `runtype agents pull <name>`                 | Prints an agent as the JSON file that `agents ensure` reads. `-o <file>` writes it to a file.                                                                     |
| `runtype agents skills ensure <file>`        | Creates or updates a Runtype Agent Skill from a JSON definition file. See [Ensure flags](#ensure-flags).                                                          |
| `runtype agents skills pull <name>`          | Prints a Runtype Agent Skill as the JSON file that `ensure` reads.                                                                                                |
| `runtype agents aliases`                     | Lists, activates, archives, and rolls back release aliases.                                                                                                       |
| `runtype agents deployments list <agent-id>` | Lists an agent's deployment receipts, newest first.                                                                                                               |
| `runtype agents promote`                     | Prepares, validates, evaluates, and activates a release.                                                                                                          |
| `runtype agents export-runtime <agent-id>`   | Exports an agent for self-hosting, as JSON or, with `--format bundle`, as a zip that includes the prebuilt runtime.                                               |
| `runtype agents task`                        | Runs a multi-session Marathon task. `runtype marathon` is the same command.                                                                                       |

The `runtype agent-versions` commands (`list`, `get`, `published`, and `publish`) manage the saved versions of an agent.

For `ensure`, aliases, and promotion, see [Manage agents as code](/user-guide/agents/manage-agents-as-code). For Marathon, see [Marathon long-running tasks](/user-guide/agents/marathon-long-running-tasks).

## Records

The `runtype records` commands manage records:

| Command                                              | Description                                                                                                                                |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `runtype records list`                               | Lists records, 20 at a time by default. Filter with `--type` or `--owner-id`.                                                              |
| `runtype records get <record-id>`                    | Shows one record.                                                                                                                          |
| `runtype records create --name <name> --type <type>` | Creates a record. `--metadata <json>` sets its metadata. `--owner-id` sets its owner key.                                                  |
| `runtype records update <record-id>`                 | Updates a record. Accepts `--name`, `--type`, `--metadata`, `--owner-id`, `--clear-owner`, or `--from-file <file>`.                        |
| `runtype records delete <record-id>`                 | Deletes a record.                                                                                                                          |
| `runtype records bulk-delete --from-file <file>`     | Deletes the records listed in a JSON file, such as `{"ids": ["<record-id>"]}`.                                                             |
| `runtype records bulk-edit --from-file <file>`       | Edits the metadata of many records from a JSON payload file.                                                                               |
| `runtype records results <record-id>`                | Lists the flow results for a record. Filter with `--flow-id`, `--batch-id`, or `--status`.                                                 |
| `runtype records costs <record-id>`                  | Shows the cost of the runs for a record.                                                                                                   |
| `runtype records export`                             | Exports records as JSON or CSV. `--format csv` selects CSV, `--output <file>` writes a file, and `--limit` sets the maximum (default 100). |
| `runtype records typegen`                            | Generates TypeScript declarations for your collection schemas. `--output <file>` writes them to a file.                                    |

The following command creates a record with metadata:

```bash
runtype records create --name "Order 1042" --type order \
  --metadata '{"status": "shipped", "total": 42.5}'
```

For more information, see [Creating and managing Records](/user-guide/records/creating-and-managing-records).

## Secrets

The `runtype secrets` commands manage secrets. Secret values are write-only, so no command prints them:

| Command                              | Description                                                                                                                        |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `runtype secrets list`               | Lists secrets.                                                                                                                     |
| `runtype secrets get <secret-id>`    | Shows one secret's details, without its value.                                                                                     |
| `runtype secrets create --key <key>` | Creates a secret. Without `--value`, the CLI reads the value from stdin. `--description` sets its description.                     |
| `runtype secrets update <secret-id>` | Replaces a secret's value or description. When you change the value, pass the current version with `--expected-version <version>`. |
| `runtype secrets delete <secret-id>` | Deletes a secret.                                                                                                                  |
| `runtype secrets check <key>...`     | Reports which of the named keys exist, are missing, or are revoked.                                                                |

A secret key starts with a letter and contains only letters, digits, and underscores. `runtype secrets create` also accepts `--product-tenant-id` or `--end-user-id` to scope the secret to one product tenant or end user.

The following command creates a secret from an environment variable, so the value doesn't appear in your shell history:

```bash
printf '%s' "$STRIPE_API_KEY" | runtype secrets create --key STRIPE_API_KEY
```

For more information, see [Managing secrets](/user-guide/settings/managing-secrets).

## Schedules

The `runtype schedules` commands manage schedules:

| Command                                   | Description                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `runtype schedules list`                  | Lists schedules.                                                                                                         |
| `runtype schedules get <schedule-id>`     | Shows one schedule.                                                                                                      |
| `runtype schedules runs <schedule-id>`    | Lists the runs of a schedule.                                                                                            |
| `runtype schedules create`                | Creates a recurring flow schedule. Requires `--flow`, `--cron`, and `--timezone`.                                        |
| `runtype schedules update <schedule-id>`  | Updates a schedule. Accepts `--flow` or `--agent` to change the target, `--cron`, `--timezone`, or `--from-file <file>`. |
| `runtype schedules pause <schedule-id>`   | Pauses a schedule.                                                                                                       |
| `runtype schedules resume <schedule-id>`  | Resumes a paused schedule.                                                                                               |
| `runtype schedules run-now <schedule-id>` | Starts a run immediately.                                                                                                |
| `runtype schedules delete <schedule-id>`  | Deletes a schedule.                                                                                                      |

The following command runs a flow at 9:00 every day in the `America/New_York` time zone:

```bash
runtype schedules create --flow <flow-id> \
  --cron "0 9 * * *" --timezone America/New_York
```

For more information, see [What are Schedules?](/user-guide/schedules/what-are-schedules).

## Surfaces

The `runtype surfaces` commands view surfaces:

| Command                                                 | Description                                                                                                              |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `runtype surfaces list`                                 | Lists surfaces. Filter with `--type` or `--status`.                                                                      |
| `runtype surfaces get <surface-id>`                     | Shows one surface.                                                                                                       |
| `runtype surfaces test <surface-id>`                    | Sends a sample GitHub event to a GitHub surface. Requires `--fixture`, `--repo <owner/repository>`, and `--pr <number>`. |
| `runtype surfaces ensure <file> --product <product-id>` | Creates or updates a surface of a product from a JSON definition file. See [Ensure flags](#ensure-flags).                |
| `runtype surfaces pull <name> --product <product-id>`   | Prints a surface as the JSON file that `ensure` reads.                                                                   |

## Evals

The `runtype eval` commands submit and read evals:

| Command                                                 | Description                                                                                                                  |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `runtype eval run [filter]`                             | Discovers `*.eval.ts` suites, runs them, and exits with 0 when they pass, 1 when they fail, and 2 for a configuration error. |
| `runtype eval submit --flow <flow-id> --records <file>` | Runs a flow against the record IDs in a JSON file. `--name` names the eval batch.                                            |
| `runtype eval list`                                     | Lists eval batches. Filter with `--flow`.                                                                                    |
| `runtype eval results <batch-id>`                       | Shows the results of an eval batch.                                                                                          |
| `runtype eval compare <group-id>`                       | Compares the eval batches in a group.                                                                                        |

The records file for `runtype eval submit` is a JSON array of record IDs, or an object with a `recordIds` array. For the options of `runtype eval run`, see [Manage evals as code](/user-guide/evals/manage-evals-as-code).

## Products

The `runtype products` commands manage products:

| Command                                                     | Description                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `runtype products list`                                     | Lists products. Accepts `--limit` and `--cursor`.                                                                                                                                                                                                                                    |
| `runtype products get <product-id>`                         | Shows one product.                                                                                                                                                                                                                                                                   |
| `runtype products init --from <url>`                        | Validates an agent card at `<url>` and creates a product from it. `--name` sets the product name. `--open` finishes the import in the dashboard instead.                                                                                                                             |
| `runtype products stack declare <product-id> --file <file>` | Declares what the product is built on, such as frameworks and services, from a JSON file. The declaration replaces the previous one.                                                                                                                                                 |
| `runtype products ensure <file>`                            | Creates or updates a product from a JSON definition file. See [Ensure flags](#ensure-flags).                                                                                                                                                                                         |
| `runtype products pull <name>`                              | Prints a product as the JSON file that `ensure` reads.                                                                                                                                                                                                                               |
| `runtype products ensure-fpo <file>`                        | Converges a whole Full Product Object: the product, its capabilities, and its surfaces. Also accepts `--prune`, which removes product-scoped capabilities and surfaces that the file doesn't list, and `--hash-probe`, which skips the upload when the live product already matches. |
| `runtype products pull-fpo <name>`                          | Prints a product graph as the Full Product Object that `ensure-fpo` reads. Records, schedules, and secrets aren't included.                                                                                                                                                          |

For more information about importing, see [Importing products](/developer-guides/guides/importing-products).

## Ensure flags

The `ensure` commands for flows, tools, products, surfaces, Runtype Agent Skills, and `products ensure-fpo` accept these flags:

| Flag                            | What it does                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| `--dry-run`                     | Prints the plan without writing, and the `remoteHash` to pass to `--expected-remote-hash`. |
| `--expect-no-changes`           | Plans without writing and exits with code 1 on any drift.                                  |
| `--overwrite-managed`           | Converges even when the last edit came from the dashboard.                                 |
| `--expected-remote-hash <hash>` | Applies only while the live entity still has the hash that a dry run printed.              |
| `--json`                        | Prints the result as JSON.                                                                 |

The flow and Runtype Agent Skill commands also accept `--release <mode>` (`none` or `publish`), `--label <text>`, and `--notes <text>`. `runtype tools ensure <file>` and `runtype tools pull <name>` work like the flow commands.

`runtype client-tokens ensure <file>` creates or updates a client token, matched by name, from a JSON definition file. It accepts `--dry-run`, `--expect-no-changes`, and `--json`, and never deletes or regenerates a token.

## Other command groups

Run `runtype --help` to list every command group. The groups that this page doesn't cover include `tools`, `models`, `batch`, `conversations`, `collections`, `api-keys`, `client-tokens`, `skills`, `mcp`, `deploy`, and `config`.

## Next steps

* [Connect Runtype to coding agents](/developer-guides/integrations/connect-coding-agents): set up the CLI and MCP connection for a coding agent.
* [Manage agents as code](/user-guide/agents/manage-agents-as-code): converge agents from source control and promote releases from CI.
* [Manage evals as code](/user-guide/evals/manage-evals-as-code): run eval suites as a CI gate with `runtype eval run`.
* [Working with logs](/user-guide/logs/working-with-logs): filter and read the logs that `runtype logs` returns.