@apiruntime/cli

Official CLI for the API Runtime platform. Deploy static sites, manage projects, and interact with your API Runtime workspace from the terminal.

Install

npm install -g @apiruntime/cli
# or run without installing
npx @apiruntime/cli <command>

Requires Node.js ≥ 18.

Auth

Store your API key (human workflow)

apiruntime login

You'll be prompted to paste an API key. The key is saved to ~/.apiruntime/config.json (mode 600 on POSIX systems).

Environment variable (CI / scripts)

Set APIRUNTIME_API_KEY in your shell or CI environment to bypass the local config file. The env var always takes precedence over the stored key.

export APIRUNTIME_API_KEY=apk_xxxxxxxx.yyyyyyyy
apiruntime deploy

Short-lived CLI token (AI agents / MCP)

If you're using the API Runtime MCP server, generate a short-lived token and pass it directly to the CLI. No stored credentials needed.

# Get token from MCP generate_cli_token, then:
export APIRUNTIME_CLI_TOKEN=eyJhbGciOiJIUzI1NiIs...
npx @apiruntime/cli@latest deploy ./app_site --yes

Or pass it inline with --token:

npx @apiruntime/cli@latest deploy ./app_site --token eyJhbGciOiJIUzI1NiIs... --yes

Tokens expire after 15 minutes. Reuse the same token for all commands in a session — only generate a new one if the CLI returns HTTP 401.

Project config

Init

apiruntime init

Creates apiruntime.json in the current directory. You'll be prompted for a project ID (find yours in the dashboard).

To skip the prompt:

apiruntime init --project my-project-id

Config file format

{
  "project_id": "my-project-id",
  "deploy": {
    "dist_dir": "./dist",
    "fallback": "index.html",
    "exclude": ["*.map", "node_modules/**"]
  }
}

| Field | Description | |---|---| | project_id | Your API Runtime project ID | | deploy.dist_dir | Directory to deploy (default ./dist) | | deploy.fallback | SPA fallback file for client-side routing (e.g. index.html) | | deploy.exclude | Glob patterns to exclude from upload |

Deploy

apiruntime deploy [dir]

Deploys the contents of [dir] (or dist_dir from config, or ./dist) to your project.

What it does

1. Hashes every file locally (SHA-256)
2. Sends a manifest to the API Runtime backend
3. Backend diffs — only changed or new files are returned
4. Lists current server files and computes stale files (files on the server that no longer exist locally)
5. Uploads changed files in parallel via presigned R2 PUT URLs
6. Finalises — deletes stale files, enables static site mode, and purges CDN cache for affected files

On a second deploy with no changes, every file will show as skipped (cached).

Flags

| Flag | Description | |---|---| | --project <id> | Override the project ID from config | | --yes | Skip confirmation prompts | | --dry-run | Show what would be uploaded without uploading | | --token <jwt> | Authenticate with a short-lived CLI token instead of an API key | | --dev | Deploy to the active dev session's preview instead of live | | --dev-session <id> | Deploy to a specific dev session's preview |

Examples

# Deploy ./dist using config
apiruntime deploy

# Deploy a specific directory
apiruntime deploy ./build

# Dry run to see what would change
apiruntime deploy --dry-run

# CI / non-interactive
apiruntime deploy --yes

# Agent / MCP workflow
npx @apiruntime/cli@latest deploy ./app_site --token <cli-token> --yes

Dev sessions (preview-first workflow)

Test changes on an isolated preview before touching live:

# Start a session — prints preview API + site URLs
apiruntime dev

# Deploy your build to the session's preview instead of live
apiruntime deploy --dev

# Happy? Apply the session's changes to live
apiruntime promote

# Or tear the session down without touching live
apiruntime stop

While a session is active, deploy --dev (or --dev-session <id>) uploads into the session's isolated overlay: the preview site serves the session's files and static-site config, while live keeps serving exactly what it served before. Sessions expire on their own if you walk away.

Agent / MCP workflow

AI agents connected via MCP should prefer the CLI over manual file uploads. The typical session looks like:

1. MCP: generate_cli_token
   ← { "token": "eyJhbGciOiJIUzI1NiIs..." }

2. Shell: export APIRUNTIME_CLI_TOKEN=<token>

3. Shell: npx @apiruntime/cli@latest deploy ./app_site --yes
   → hashes, diffs, uploads changed files, deletes stale files, purges cache

4. Reuse the same token for any additional CLI commands within 15 minutes

If Node.js / npx is not available, fall back to MCP manage_files (presign_batch → upload → finalize_batch).

Other commands

# List your projects
apiruntime projects

# Create / update apiruntime.json
apiruntime init --project my-project-id

# Clone a project's endpoints, library, and site files to a local folder
apiruntime pull

Troubleshooting

"API key not found" / "Not authenticated"

Run apiruntime login, set APIRUNTIME_API_KEY, or pass --token <jwt>.

"project_id is not set"

Run apiruntime init in your project root or pass --project <id>.

"dist_dir does not exist"

Make sure you run your build step before deploying, e.g. npm run build && apiruntime deploy.

"File storage not available on your plan"

Static site hosting requires a paid plan. Upgrade at apiruntime.dev/pricing.

Upload fails with a network error

Check your internet connection. The CLI will surface the HTTP status and backend error message if the API returns one.

API base URL

By default the CLI talks to https://api.apiruntime.dev. Override with:

export APIRUNTIME_API_URL=https://api.apiruntime.dev

License

MIT © API Runtime