Skip to navigation
Getting Started

Runtype CLI reference

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:

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:

npm install -g @runtypelabs/cli

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

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.

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:

CommandResult
runtype updateInstalls the newest stable release. It takes effect on the next invocation.
runtype update --checkReports whether an update is available, without installing it.
runtype update --rollbackReturns 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.
  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:

CommandDescription
runtype loginOpens 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 signupOpens the browser sign-in page, which links to account creation.
runtype auth statusShows which login the current directory uses, and why.
runtype auth accountsLists the stored logins.
runtype auth switch [<org-id>]Sets the default login for directories without a project link.
runtype auth whoamiShows the signed-in user and organization.
runtype auth export-keyPrints 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.
runtype unlinkRemoves the nearest project link.

Replace <api-key> with an API key from Settings > API in the dashboard. For more information, see Managing API keys.

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

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.

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:

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:

OptionDescription
--jsonPrints the result as JSON instead of formatted text.
--no-inputTurns off prompts and browser sign-in. A delete, bulk-delete, revoke, or reset command then also requires --yes.
-y, --yesConfirms 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, --verbosePrints 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:

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:

OptionDescription
-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-streamWaits for the complete response instead of streaming it.
--jsonPrints one final JSON result.
--jsonlPrints each stream event as a JSON line, followed by an execution_summary event.

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:

OptionDescription
-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.
--debugPrints 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:

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:

OptionDescription
--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, --conversationFilters by the ID of that resource.

The following command lists failed flow runs from one day:

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.

Flows

The runtype flows commands manage flows:

CommandDescription
runtype flows listLists 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.
runtype flows ensure <file>Creates or updates a flow from a JSON definition file. See 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:

CommandDescription
runtype agents listLists 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.
runtype agents ensureCreates 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.
runtype agents skills pull <name>Prints a Runtype Agent Skill as the JSON file that ensure reads.
runtype agents aliasesLists, activates, archives, and rolls back release aliases.
runtype agents deployments list <agent-id>Lists an agent’s deployment receipts, newest first.
runtype agents promotePrepares, 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 taskRuns 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. For Marathon, see Marathon long-running tasks.

Records

The runtype records commands manage records:

CommandDescription
runtype records listLists 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 exportExports records as JSON or CSV. --format csv selects CSV, --output <file> writes a file, and --limit sets the maximum (default 100).
runtype records typegenGenerates TypeScript declarations for your collection schemas. --output <file> writes them to a file.

The following command creates a record with metadata:

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

For more information, see Creating and managing Records.

Secrets

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

CommandDescription
runtype secrets listLists 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:

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

For more information, see Managing secrets.

Schedules

The runtype schedules commands manage schedules:

CommandDescription
runtype schedules listLists schedules.
runtype schedules get <schedule-id>Shows one schedule.
runtype schedules runs <schedule-id>Lists the runs of a schedule.
runtype schedules createCreates 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:

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

For more information, see What are Schedules?.

Surfaces

The runtype surfaces commands view surfaces:

CommandDescription
runtype surfaces listLists 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.
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:

CommandDescription
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 listLists 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.

Products

The runtype products commands manage products:

CommandDescription
runtype products listLists 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.
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.

Ensure flags

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

FlagWhat it does
--dry-runPrints the plan without writing, and the remoteHash to pass to --expected-remote-hash.
--expect-no-changesPlans without writing and exits with code 1 on any drift.
--overwrite-managedConverges 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.
--jsonPrints 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