π 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
```bash
npm install -g @runtypelabs/cli
```
Or run without installing:
```bash
npx @runtypelabs/cli@latest
```
## 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.
```bash
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!
```bash
# 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
```bash
# Browser login
runtype login
# API key login for CI or non-interactive use
runtype login --api-key
```
### 2. Work With Agents, Flows, and Records
```bash
# 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 --message "Summarize this document"
# Create a flow
runtype flows create --name "My Flow" --description "Description"
# Run a flow directly with variables
runtype dispatch --flow --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.
```bash
# 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:
```bash
# 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 ` | π | Emoji for the runner |
| `--finish-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.
```bash
# 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:
```bash
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/.yaml|yml|json` (repo) β `~/.runtype/marathons/playbooks/.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).
```yaml
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:
```bash
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:
```bash
# 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:
```yaml
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.
```bash
# 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.
```bash
# 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 ` 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).
```bash
# 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.
```bash
runtype init
runtype init --api-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 ` |
| `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 ` | Get flow details |
| `flows create -n ` | Create a new flow |
| `flows run ` | Execute a flow via dispatch |
| `flows delete ` | Delete a flow |
### `runtype records`
Manage records.
| Subcommand | Description |
| ------------------------------------ | ---------------------------------------------------------------- |
| `records list` | List all records (`--type`, `--limit`) |
| `records get ` | Get record details |
| `records create -n -t ` | Create a new record (`--metadata `) |
| `records delete ` | Delete a record |
| `records export` | Export records to file (`--format json\|csv`, `--output `) |
### `runtype agents`
Manage agents.
| Subcommand | Description |
| ---------------------------------- | ----------------------------------------------- |
| `agents list` | List all agents |
| `agents get ` | Get agent details |
| `agents create -n ` | Create a new agent |
| `agents execute -m ` | Execute an agent with a message |
| `agents task -g ` | Run a multi-session task (see Marathon section) |
| `agents delete ` | Delete an agent |
### `runtype persona`
Set up the [Persona](https://github.com/runtypelabs/persona) chat widget against Runtype: create an agent, create a client token, and output an embed snippet.
| Subcommand | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `persona init` | One-step onboarding (`--agent-name`, `--token-name`, `--environment`, `--origins`, `--format`, `--print-snippet`, `--json`, `--api-url`, etc.) |
Example:
```bash
npx @runtypelabs/cli@latest persona init --agent-name "Support" --no-tty
npx @runtypelabs/cli@latest persona init --json --agent-name "Support" --token-name "Website"
```
### `runtype dispatch`
Execute a flow or agent via the dispatch API.
```bash
runtype dispatch --flow --message "Hello"
runtype dispatch --agent --message "Hello"
runtype dispatch --flow --record
runtype dispatch --flow --record-json data.json
runtype dispatch --flow --variable key=value --variable key2=value2
runtype dispatch --flow --no-stream --json
```
### `runtype prompts`
Manage prompts.
| Subcommand | Description |
| ------------------- | ---------------------------------------------------- |
| `prompts list` | List all prompts |
| `prompts get ` | Get prompt details |
| `prompts test ` | Test a prompt (`-i `, `--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 ` | Enable a model |
| `models disable ` | Disable a model configuration |
| `models default ` | Set a model configuration as default |
| `models usage` | Show model usage statistics |
### `runtype batch`
Manage batch operations.
| Subcommand | Description |
| -------------------------------------------- | ---------------------------------- |
| `batch submit -f -r ` | Submit a batch job |
| `batch status ` | Check batch job status (`--watch`) |
| `batch cancel ` | Cancel a batch job |
### `runtype eval`
Manage evaluations.
| Subcommand | Description |
| ------------------------------------------- | -------------------------------------------- |
| `eval submit -f -r ` | Submit an eval batch (`-n `) |
| `eval list` | List eval batches (`--flow `, `--limit`) |
| `eval results ` | Get eval batch results |
| `eval compare ` | Compare evals in a group |
### `runtype schedules`
Manage scheduled flow runs.
| Subcommand | Description |
| ---------------------------------------- | ------------------------------- |
| `schedules list` | List all schedules |
| `schedules get ` | Get schedule details |
| `schedules create -f -c ` | Create a schedule (`-n `) |
| `schedules pause ` | Pause a schedule |
| `schedules resume ` | Resume a paused schedule |
| `schedules run-now ` | Trigger immediate execution |
| `schedules delete ` | Delete a schedule |
### `runtype api-keys`
Manage API keys.
| Subcommand | Description |
| --------------------------- | ------------------------------------------------ |
| `api-keys list` | List your API keys |
| `api-keys get ` | Get API key details |
| `api-keys create -n ` | Create a new API key |
| `api-keys delete ` | Delete an API key (`--yes` to skip confirmation) |
| `api-keys regenerate ` | Regenerate an API key |
| `api-keys analytics` | Show usage analytics (`--key `) |
### `runtype products`
Manage products.
| Subcommand | Description |
| ---------------------------- | ------------------------------------------------------------- |
| `products init --from ` | Import a product from an authenticated external A2A agent URL |
```bash
# After logging in, import an external A2A agent
runtype products init --from https://example.com/.well-known/agent-card.json
runtype products init --from --name "Custom Name"
```
### `runtype flow-versions`
Manage flow versions.
| Subcommand | Description |
| ----------------------------------------------- | ---------------------------- |
| `flow-versions list ` | List all versions for a flow |
| `flow-versions get ` | Get a specific version |
| `flow-versions published ` | Get the published version |
| `flow-versions publish -v ` | 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
```bash
# 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 ` | Override API URL |
## Development
### Local Development Setup
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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 , 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:
```bash
# 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:
```bash
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:
```bash
RUNTYPE_API_URL=http://localhost:8787 pnpm dev -- auth login --api-key YOUR_API_KEY
```
**Testing a single command** (from `packages/cli`):
```bash
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
```bash
# 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:
```bash
# 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
