👋 Hey there! We're here to help you build intelligent products.

You are looking at...

The Runtype CLI

This is our command-line interface for the platform, which includes Marathon, our harness for long-running tasks and deep workflow analysis.

Installation

npm install -g @runtypelabs/cli

Or run without installing:

npx @runtypelabs/cli@latest <command>

Start Here

The easiest way to try Runtype starting at the CLI is to run a Marathon task. If you are not logged in yet, the CLI will guide you through login or signup first.

npx @runtypelabs/cli@latest marathon researcher \
  -g "fetch the home page of hacker news, read the articles related to AI, and summarize them. Use your firecrawl tool liberally" \
  --model qwen/qwen3.5-397b-a17b \
  --tools firecrawl \
  --fresh \
  --max-sessions 2

Marathon can research on the web, edit code in your current repo, or run code in a sandbox. As it does this, you get full insight into what is happening during each run. You can have it process very long tasks with 1000+ tool calls and get an output of the session on your local machine or (optionally) store it within Runtype.

Keep in mind it's a harness meant to aid understanding and analysis of AI workflows. How LLMs and tools interact with the system and user prompts to solve problems over many runs. It's a research harness, built for people building on top of AI.

It's not aiming to replace your favorite AI coding assistant, even though it'll gladly show you it's work as it makes a valiant effort!

# Edit code in the current repo
runtype marathon "Code Editor" --goal "Refactor the theme editor to use modern UX best practices"

# Build something and deploy it publicly
runtype marathon calculator --goal "Build a calculator in 3d and deploy it publicly" --model claude-sonnet-4-6 --sandbox daytona

Quick Start

1. Get Authenticated

# Browser login
runtype login

# API key login for CI or non-interactive use
runtype login --api-key <key>

2. Work With Agents, Flows, and Records

# List available agents
runtype agents list

# Run a saved dashboard agent by ID, which uses your configured custom and cloud tools in a marathon
runtype marathon agent_abc123 --goal "Refactor the theme editor to use modern UX best practices"

# Run an agent directly
runtype dispatch --agent <agent-id> --message "Summarize this document"

# Create a flow
runtype flows create --name "My Flow" --description "Description"

# Run a flow directly with variables
runtype dispatch --flow <flow-id> --variable customerName=Alyss --variable priority=high --message "Hello, this is Claudia. Nice to meet you."

# Create a record
runtype records create --name "My Record" --type "document"

3. Run Multi-Session Agent Tasks

Use runtype marathon to run long-running tasks with real-time streaming output. If you want to try it without installing first, use npx @runtypelabs/cli@latest marathon .... Swap the agent, model, tools, and execution environment depending on whether you want to research, edit code, or build and ship something end-to-end.

# Session-limited research task that writes results into the folder you run it in
runtype marathon researcher -g "fetch the home page of hacker news, read the articles related to AI, and summarize them. Use your firecrawl tool liberally" --model qwen/qwen3.5-397b-a17b --tools firecrawl --fresh --max-sessions 2

# Edit code in the current repo
runtype marathon "Code Editor" --goal "Refactor the theme editor to use modern UX best practices"

# Build something and deploy it publicly
runtype marathon calculator --goal "Build a calculator in 3d and deploy it publicly" --model claude-sonnet-4-6 --sandbox daytona

Customizing the Runner Animation

The marathon header displays an animated runner that laps around the border. You can customize the emojis:

# Custom runner and finish line emojis
runtype marathon "Code Builder" --goal "Build it" --runner-char 🚀 --finish-char 🌕

runtype marathon "Code Builder" --goal "Build it" --runner-char 🏎️ --finish-char 🏆

# Hide the runner, the finish line, or both for a clean border
runtype marathon "Code Builder" --goal "Build it" --no-runner
runtype marathon "Code Builder" --goal "Build it" --no-runner --no-finish

| Flag | Default | Description | | ---------------------- | ------- | ------------------------------------------------- | | --runner-char <char> | 🏃 | Emoji for the runner | | --finish-char <char> | 🏁 | Emoji for the finish line | | --no-runner | | Hide the runner emoji from the header border | | --no-finish | | Hide the finish line emoji from the header border |

Custom Playbooks

Playbooks let you define custom workflows with milestones, model overrides, verification settings, and rules in a single YAML file.

# Run with a custom playbook
runtype marathon "Minimal design library" \
  --playbook design-library \
  --goal "Create a clean, modern component library with a blue/slate palette" \
  --sandbox daytona

# Playbooks are loaded from .runtype/marathons/playbooks/ (first checks folder CLI is ran from, then ~/.runtype/)

From the folder where you want to run the CLI, create the playbook with:

mkdir -p .runtype/marathons/playbooks

cat > .runtype/marathons/playbooks/design-library.yaml <<'EOF'
name: design-library
description: Generate a styled component library (headers, buttons, forms) and deploy a live preview

rules: |
  IMPORTANT: Before doing anything else, create a new directory for this project
  (e.g. "design-library/" or a name derived from the goal). All files must be
  created inside that directory — do NOT write files in the current working directory.
  Use vanilla HTML + CSS only — no frameworks, no build tools.
  Every component must be responsive and accessible (aria labels, focus states).
  Use CSS custom properties for all colors, spacing, and typography so the
  entire theme can be changed by editing a single :root block.
  The final index.html should be a showcase page displaying every component variant.

milestones:
  - name: research
    description: Analyze the style direction and plan the component set
    model: gpt-5-mini
    instructions: |
      FIRST: Create a new project directory (e.g. "design-library/" or a name
      derived from the goal). All files for this project go inside that directory.
      Do NOT look at or use any existing files in the current working directory.

      Then, read the goal to understand the desired visual style.
      Decide on a color palette, typography scale, and spacing system.
      List the exact components to build:
        - Header: full-width navbar with logo area, nav links, and mobile menu
        - Buttons: primary, secondary, outline, ghost, destructive — in sm/md/lg sizes
        - Forms: text input, textarea, select, checkbox, radio, toggle — with labels and validation states
      Write design-tokens.md inside the project directory capturing your decisions.
    completionCriteria:
      type: evidence
      minReadFiles: 1

  - name: build
    description: Create the HTML, CSS, and showcase page
    model: claude-sonnet-4-6
    instructions: |
      Create the project files:
        1. styles/tokens.css — CSS custom properties for the entire theme
        2. styles/components.css — all component styles using the tokens
        3. index.html — showcase page that renders every component and variant
      Make sure:
        - The showcase page has sections for Headers, Buttons, and Forms
        - Each section shows all variants side by side
        - The page looks good at mobile (375px) and desktop (1200px) widths
        - All interactive elements have hover/focus/active states
      If a sandbox is available, use `deploy_sandbox` to deploy the showcase
      as a live preview so the user can see it in their browser.
    completionCriteria:
      type: sessions
      minSessions: 1

  - name: polish
    description: Refine details, test responsiveness, and deploy
    model: gemini-3-flash
    instructions: |
      Review the showcase page in the browser preview.
      Fix any visual issues, alignment problems, or missing states.
      Ensure the page title and meta description reflect the library name.
      Verify the deployed preview URL is accessible.
    completionCriteria:
      type: never
    canAcceptCompletion: true
EOF

Search order: Exact path → .runtype/marathons/playbooks/<name>.yaml|yml|json (repo) → ~/.runtype/marathons/playbooks/<name>.yaml|yml|json (user).

Completion criteria types:

• evidence — advances when enough files have been read (minReadFiles)
• sessions — advances after N sessions (minSessions)
• planWritten — advances when the agent writes its plan artifact
• never — only the agent's TASK_COMPLETE signal can advance (if canAcceptCompletion: true)

Playbook policies:

The optional policy block lets you restrict what the agent can do at runtime. Policies are additive restrictions — they can only narrow behavior, never override global safety denies (e.g. .env files and private keys are always blocked).

name: blog-writer
policy:
  allowedReadGlobs: ['content/**', 'templates/**']
  allowedWriteGlobs: ['content/**']
  blockedTools: ['search_repo']
  blockDiscoveryTools: true
  requirePlanBeforeWrite: true
  requireVerification: true
  outputRoot: 'content/'
milestones:
  - ...

| Field | Type | Description | | ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | | allowedReadGlobs | string[] | Glob patterns for allowed read paths. If set, reads outside these are blocked. | | allowedWriteGlobs | string[] | Glob patterns for allowed write paths. If set, writes outside these are blocked. The plan file is always writable regardless. | | blockedTools | string[] | Tool names to block entirely (e.g. ["write_file", "search_repo"]). | | blockDiscoveryTools | boolean | Block search_repo, glob_files, tree_directory, and list_directory. | | requirePlanBeforeWrite | boolean | Require the agent to write its plan before any other file writes. | | requireVerification | boolean | Require verification before TASK_COMPLETE. | | outputRoot | string | For creation tasks: confine writes to this directory (e.g. "public/"). |

Marathon Anatomy

┌─ marathon ──────────────────────────────────────────────────────┐
│                                                                 │
│  ┌─ playbook (optional) ──────────────────────────────────┐     │
│  │  Defines milestones, models, verification, rules,     │     │
│  │  and policy constraints                               │     │
│  │  .runtype/marathons/playbooks/tdd.yaml                │     │
│  └────────────────────────────────────────────────────────┘     │
│           │                                                     │
│           ▼                                                     │
│  ┌─ milestone 1 ──┐  ┌─ milestone 2 ──┐  ┌─ milestone 3 ─────┐  |
│  │ research        │  │ test-design     │  │ execution       │  |
│  │                 │  │                 │  │                 │  |
│  │  run 1          │  │  run 3          │  │  run 5          │  |
│  │    checkpoint ──┤  │    checkpoint ──┤  │    checkpoint ──┤  |
│  │  run 2          │  │  run 4          │  │  run 6          │  |
│  │    checkpoint ──┤  │    checkpoint ──┘  │    checkpoint ──┘  |
│  │  (advances) ────┘  │                 |  │                 │  |
│  └─────────────────┘  └─────────────────┘  └──── finish ─────┘  |
│                                                                 |
│  ┌─ rules (optional) ────────────────────────────────┐          |
│  │  Repo-wide standards applied to ALL milestones    │          │
│  │  .runtype/marathons/rules/*.md                    │          │
│  └───────────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────────┘

Vocabulary:
  marathon     The overall autonomous task runner
  playbook     Custom workflow definition
                (optional, default: research→planning→execution)
  milestones   Behavioral phases the agent works through
  runs         Individual agent sessions within a milestone
  checkpoint   Pause between runs for human review/steering
  finish       Task completion

What's optional:
  ✓ Playbook    Without one, uses default workflow (research→planning→execution)
  ✓ Rules       Without them, agent follows only playbook/milestone instructions
  ✓ Models      Without overrides, uses CLI --model flag or default
  ✓ Verification Without it, no verification gate between milestones
  ✓ Policy      Without one, only global safety denies apply

Reasoning / Thinking

Marathon enables model reasoning by default for models that support it (Gemini 3, o-series, GPT-5, etc.). When active, the model's thinking process streams to the TUI in real time. To disable:

runtype marathon "Code Builder" --goal "Fix the bug" --no-reasoning

Fallback Models

When an upstream model provider returns a transient error (e.g. overload, rate limit), marathon can automatically retry and then fall back to a different model instead of dying mid-run.

CLI flag — applies to all phases:

# If claude-opus-4-6 fails, retry once then fall back to claude-sonnet-4-5
runtype marathon "Code Builder" --goal "Refactor auth" \
  --model claude-opus-4-6 \
  --fallback-model claude-sonnet-4-5

Playbook — per-milestone fallback chains:

milestones:
  - name: research
    model: claude-sonnet-4-5
    fallbackModels:
      - gpt-4o # string shorthand
      - gemini-3-flash
    instructions: |
      Research the codebase...

  - name: execution
    model: claude-opus-4-6
    fallbackModels:
      - model: claude-sonnet-4-5 # object form with overrides
        temperature: 0.5
      - model: gpt-4o
        maxTokens: 8192
    instructions: |
      Implement the changes...

Playbook per-milestone fallbacks take priority over the CLI --fallback-model flag. The fallback chain always starts with a retry (5s delay) before trying alternative models.

Tool Context Modes

When a marathon runs multiple sessions, tool call/result pairs from previous sessions are preserved in the conversation history. The --tool-context flag controls how older tool results are stored to balance cost and re-readability:

| Mode | Behavior | Best for | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | hot-tail (default) | Older results are offloaded into internal marathon state and referenced by opaque ids. Model can re-read them via read_offloaded_output. | Multi-session tasks that may need to revisit earlier results | | observation-mask | Older results replaced with [Output from X masked — re-run the tool if needed]. No disk I/O. | Cost-sensitive or focused tasks | | full-inline | All results stay inline forever. No compaction. | Short tasks, debugging, baseline comparisons |

The --tool-window flag controls which results are "hot" (inline) vs "cold" (compacted):

• session (default): Current session's results stay inline; all previous sessions' results are compacted.
• A number (e.g. 10): Keep the last N tool result messages inline regardless of session boundaries.

# Default: hot-tail mode with session-based compaction window
runtype marathon "Code Builder" --goal "Fix the bug"

# SWE-agent style: mask old results, keep last 10 inline
runtype marathon "Code Builder" --goal "Fix the bug" \
  --tool-context observation-mask --tool-window 10

# Everything inline, no compaction (short tasks or debugging)
runtype marathon "Code Builder" --goal "Fix the bug" --tool-context full-inline

Automatic History Compaction

Marathon now manages continuation context against the active model's usable input budget instead of raw message history alone. It accounts for conversation history, tool results, tool definitions, and reserved output headroom before deciding whether to compact.

• This is enabled by default.
• The threshold is model-aware and follows the model currently selected for the run.
• Provider-native compaction is preferred when the active provider supports it. Today that means Anthropic-backed marathon runs compact at 90% of the effective input budget.
• Other models fall back to structured summary compaction at 80% of the effective input budget.
• --compact still forces compact-summary mode for resume/restart scenarios even if the threshold has not been reached.
• Use --compact-strategy auto|provider_native|summary_fallback to override the default selection.
• Use --compact-instructions "..." to tell summary compaction what state must be preserved.

# Default behavior: provider-aware auto compaction
runtype marathon "Code Builder" --goal "Refactor the auth module"

# Force summary fallback even on providers with native compaction
runtype marathon "Code Builder" --goal "Refactor the auth module" \
  --compact-strategy summary_fallback

# Preserve specific context in compact summaries
runtype marathon "Code Builder" --goal "Refactor the auth module" \
  --compact-instructions "Preserve changed files, test results, and unresolved blockers."

# Raise the threshold to 90% of the effective input budget
runtype marathon "Code Builder" --goal "Refactor the auth module" \
  --compact-threshold 90%

# Use an absolute token threshold instead
runtype marathon "Code Builder" --goal "Refactor the auth module" \
  --compact-threshold 120000

# Disable automatic history compaction
runtype marathon "Code Builder" --goal "Refactor the auth module" \
  --no-auto-compact

Percentages must include % (e.g. 80%). Bare numbers are treated as absolute token counts (e.g. 120000).

Tool Output Guardrails

Marathon also guards against oversized local tool results so they do not silently consume the whole context window.

• Outputs above the soft warning threshold are surfaced in the TUI as context notices.
• Outputs above the hard threshold are offloaded to disk and replaced with a compact reference the model can reopen with read_file.
• The default hard threshold is 100000 characters. Set --offload-threshold <chars> to tune it, or --offload-threshold off to disable it.

Built-in Tools

The --tools (or -t) flag enables built-in platform tools during agent execution. Tools are validated at startup against the built-in tools registry, and compatibility is checked against all models used in the task (including planning and execution phase models).

# Enable a single tool
runtype marathon "Code Builder" --goal "Search the web" --tools exa

# Enable multiple tools (space-separated)
runtype marathon "Code Builder" --goal "Research and generate" --tools exa firecrawl

# Short flag
runtype marathon "Code Builder" -g "Scrape docs" -t firecrawl

Available tools:

| Tool ID | Description | Model Restriction | | ----------- | ----------------------------------- | ------------------ | | exa | Semantic web search | Any model | | firecrawl | Web scraping and content extraction | Any model | | dalle | DALL-E image generation | OpenAI models only |

Not available via CLI:

• openai_web_search, anthropic_web_search, anthropic_web_fetch — provider-native tools handled automatically by compatible models
• vector-search — requires additional configuration (use the dashboard instead)
• elevenlabs-tts, elevenlabs-stt — not yet exposed in the CLI

Validation behavior:

• Unknown tool IDs produce an error listing all available tools
• Tools incompatible with the selected model(s) are rejected with a specific error
• All validation errors are reported together so you can fix them in one pass

Command Reference

runtype init

Guided onboarding wizard for first-time setup. Walks through authentication and product creation.

runtype init
runtype init --api-key <key> --name "My Product"

runtype login

Top-level alias for runtype auth login.

runtype auth

Manage authentication.

| Subcommand | Description | | ------------- | ---------------------------------------------- | | auth signup | Create a new account (alias for auth login) | | auth login | Login via browser or --api-key <key> | | auth status | Show authentication status | | auth whoami | Display current user info with billing details | | auth logout | Remove stored credentials |

runtype flows

Manage flows.

| Subcommand | Description | | ------------------------ | --------------------------- | | flows list | List all flows | | flows get <id> | Get flow details | | flows create -n <name> | Create a new flow | | flows run <id> | Execute a flow via dispatch | | flows delete <id> | Delete a flow |

runtype records

Manage records.

| Subcommand | Description | | ------------------------------------ | ---------------------------------------------------------------- | | records list | List all records (--type, --limit) | | records get <id> | Get record details | | records create -n <name> -t <type> | Create a new record (--metadata <json>) | | records delete <id> | Delete a record | | records export | Export records to file (--format json\|csv, --output <file>) |

runtype agents

Manage agents.

| Subcommand | Description | | ---------------------------------- | ----------------------------------------------- | | agents list | List all agents | | agents get <id> | Get agent details | | agents create -n <name> | Create a new agent | | agents execute <id> -m <message> | Execute an agent with a message | | agents task <agent> -g <goal> | Run a multi-session task (see Marathon section) | | agents delete <id> | Delete an agent |

runtype dispatch

Execute a flow or agent via the dispatch API.

runtype dispatch --flow <id> --message "Hello"
runtype dispatch --agent <id> --message "Hello"
runtype dispatch --flow <id> --record <record-id>
runtype dispatch --flow <id> --record-json data.json
runtype dispatch --flow <id> --variable key=value --variable key2=value2
runtype dispatch --flow <id> --no-stream --json

runtype prompts

Manage prompts.

| Subcommand | Description | | ------------------- | ---------------------------------------------------- | | prompts list | List all prompts | | prompts get <id> | Get prompt details | | prompts test <id> | Test a prompt (-i <input>, --stream/--no-stream) |

runtype models

Manage model configurations.

| Subcommand | Description | | ------------------------- | --------------------------------------------- | | models list | List your enabled model configurations | | models available | List all available models grouped by provider | | models enable <modelId> | Enable a model | | models disable <id> | Disable a model configuration | | models default <id> | Set a model configuration as default | | models usage | Show model usage statistics |

runtype batch

Manage batch operations.

| Subcommand | Description | | -------------------------------------------- | ---------------------------------- | | batch submit -f <flowId> -r <records.json> | Submit a batch job | | batch status <id> | Check batch job status (--watch) | | batch cancel <id> | Cancel a batch job |

runtype eval

Manage evaluations.

| Subcommand | Description | | ------------------------------------------- | -------------------------------------------- | | eval submit -f <flowId> -r <records.json> | Submit an eval batch (-n <name>) | | eval list | List eval batches (--flow <id>, --limit) | | eval results <id> | Get eval batch results | | eval compare <groupId> | Compare evals in a group |

runtype schedules

Manage scheduled flow runs.

| Subcommand | Description | | ---------------------------------------- | ------------------------------- | | schedules list | List all schedules | | schedules get <id> | Get schedule details | | schedules create -f <flowId> -c <cron> | Create a schedule (-n <name>) | | schedules pause <id> | Pause a schedule | | schedules resume <id> | Resume a paused schedule | | schedules run-now <id> | Trigger immediate execution | | schedules delete <id> | Delete a schedule |

runtype api-keys

Manage API keys.

| Subcommand | Description | | --------------------------- | ------------------------------------------------ | | api-keys list | List your API keys | | api-keys get <id> | Get API key details | | api-keys create -n <name> | Create a new API key | | api-keys delete <id> | Delete an API key (--yes to skip confirmation) | | api-keys regenerate <id> | Regenerate an API key | | api-keys analytics | Show usage analytics (--key <id>) |

runtype products

Manage products.

| Subcommand | Description | | ---------------------------- | ------------------------------------------------------------- | | products init --from <url> | Import a product from an authenticated external A2A agent URL |

# After logging in, import an external A2A agent
runtype products init --from https://example.com/.well-known/agent-card.json
runtype products init --from <url> --name "Custom Name"

runtype flow-versions

Manage flow versions.

| Subcommand | Description | | ----------------------------------------------- | ---------------------------- | | flow-versions list <flowId> | List all versions for a flow | | flow-versions get <flowId> <versionId> | Get a specific version | | flow-versions published <flowId> | Get the published version | | flow-versions publish <flowId> -v <versionId> | Publish a version |

runtype billing

View billing and subscription info.

| Subcommand | Description | | ----------------- | --------------------------------------- | | billing status | Show current plan and usage | | billing portal | Open the billing portal in your browser | | billing refresh | Refresh plan data from billing provider |

runtype analytics

View analytics and execution results.

| Subcommand | Description | | ------------------- | -------------------------------------------------------------------- | | analytics stats | Show account statistics | | analytics results | List execution results (--flow, --record, --status, --limit) |

Configuration

# View all configuration
runtype config get

# Get a specific key
runtype config get apiUrl

# Set API URL
runtype config set apiUrl https://api.runtype.com

# Set default model
runtype config set defaultModel gpt-4o

# Reset configuration
runtype config reset

# Show configuration file path
runtype config path

Valid config keys: apiUrl, defaultModel, defaultTemperature, outputFormat, streamResponses

Global Options

All commands support these flags:

| Flag | Description | | -------------------- | ------------------------ | | --json | Output in JSON format | | --tty / --no-tty | Force TTY / non-TTY mode | | -v, --verbose | Enable verbose output | | --api-url <url> | Override API URL |

Development

Local Development Setup

# From repository root, navigate to CLI package
cd packages/cli

# Install dependencies
pnpm install

# Copy environment template and configure for local development
cp .env.example .env
# Edit .env with your local settings (API URL, Clerk key, etc.)

# Build the CLI
pnpm build

Running the CLI Locally

Option 1: Development mode with hot reload

# Run with tsx watch (for development)
pnpm dev

# Run specific commands in dev mode
pnpm dev -- --help
pnpm dev -- auth login
pnpm dev -- config get

Option 2: Build and run directly

# Build first
pnpm build

# Run built CLI with Node.js
node dist/index.js --help
node dist/index.js auth login

Option 3: Install globally for testing

# Build first
pnpm build

# Option A: Symlink (pnpm) — global runtype uses your local package; rebuild after changes
# If you get "Unable to find the global bin directory", run: pnpm setup (then restart terminal)
pnpm link --global
# Use anywhere: runtype --help, runtype products init --from <url>, etc.
# To stop: pnpm unlink --global (from packages/cli)

# Option B: Install current directory (npm)
npm install -g .
# Now use the runtype command anywhere
runtype --help
runtype auth login
# After making changes, rebuild and reinstall: pnpm build && npm install -g .

Local Environment Configuration

Create a .env file for local development:

# Point to local API and dashboard
RUNTYPE_API_URL=http://localhost:8787
RUNTYPE_DASHBOARD_URL=http://localhost:3001

# Add your Clerk publishable key (get from Clerk dashboard)
CLERK_PUBLISHABLE_KEY=pk_test_your_key_here

# Optional: Set defaults
RUNTYPE_DEFAULT_MODEL=meta/llama3.1-8b-instruct-free
RUNTYPE_DEFAULT_TEMPERATURE=0.7
DEBUG=true

Testing against local API

To use the CLI with your local API and dashboard:

1. Run API and dashboard (from repo root): pnpm dev:api (or pnpm dev:bun) and pnpm dev:dashboard. Ensure the dashboard has NEXT_PUBLIC_RUNTYPE_API_URL=http://localhost:8787 so CLI auth creates keys against your local API.

2. Use a .env in packages/cli with RUNTYPE_API_URL and RUNTYPE_DASHBOARD_URL as above, or set them when running:

   RUNTYPE_DASHBOARD_URL=http://localhost:3001 RUNTYPE_API_URL=http://localhost:8787 pnpm dev -- auth login

3. Or skip browser auth by creating an API key in the local dashboard, then:

   RUNTYPE_API_URL=http://localhost:8787 pnpm dev -- auth login --api-key YOUR_API_KEY

Testing a single command (from packages/cli):

export RUNTYPE_DASHBOARD_URL=http://localhost:3001
export RUNTYPE_API_URL=http://localhost:8787
pnpm dev -- agents list

Or inline: RUNTYPE_DASHBOARD_URL=http://localhost:3001 RUNTYPE_API_URL=http://localhost:8787 pnpm dev -- flows list

Testing

# Run tests
pnpm test

# Watch mode
pnpm test:watch

Environment Variables

• RUNTYPE_API_URL - API base URL without a path (e.g. http://localhost:8787). Do not include /v1; the CLI adds the version prefix. Default: https://api.runtype.com

• RUNTYPE_DASHBOARD_URL - Dashboard URL (default: https://use.runtype.com)

• CLERK_PUBLISHABLE_KEY - Clerk public key for OAuth

• RUNTYPE_DEFAULT_MODEL - Default AI model (default: gpt-4o)

• RUNTYPE_DEFAULT_TEMPERATURE - Default temperature (default: 0.7)

• DEBUG - Enable debug mode

• RUNTYPE_DEV_PLAN_OVERRIDE - JSON string to override billing/plan limits in development. Injects the X-Dev-Plan-Override header into all API requests. Only effective when the API runs with ENVIRONMENT=development. Example:

  # Simulate enterprise (unlimited)
  export RUNTYPE_DEV_PLAN_OVERRIDE='{"scenarioId":"unlimited","plan":"enterprise","overrides":{}}'
  
  # Simulate slow mode
  export RUNTYPE_DEV_PLAN_OVERRIDE='{"scenarioId":"slow","plan":"trial","overrides":{"inSlowMode":true,"hourlyUsed":9,"hourlyLimit":10,"hourlyResetSeconds":600}}'

License

Apache-2.0