Forkline CLI

The forkline CLI lets you manage repositories, runners, routines, MCP servers, secrets, tokens, and analytics from your terminal. It supports human-readable tables, structured JSON output for scripting, and shell completions.

Installation

Install the forkline CLI via npm (recommended), the shell installer, a direct binary download, or from source. Every method produces the same binary; only shell completions require an extra step (see Shell completions below).

npm (recommended)

npm automatically selects the correct pre-built binary for your platform:

npm install -g @forkline/cli

Or run without installing:

npx @forkline/cli --version

npm installs a platform-specific optional dependency based on your OS, architecture, and libc:

Shell installer

The installer detects your OS, architecture, and libc (Linux glibc vs musl), downloads the latest release, verifies the SHA256 checksum, and installs the binary to /usr/local/bin if writable — otherwise $HOME/.local/bin.

curl -fsSL https://forkline.dev/install.sh | sh

Two environment variables control the installer:

Example:

FORKLINE_VERSION=0.37.2 FORKLINE_INSTALL_DIR=$HOME/bin \
  sh -c "$(curl -fsSL https://forkline.dev/install.sh)"

The shell installer supports Linux and macOS only. On Windows use npm or the direct download below.

Direct download

Grab the archive for your platform from GitHub Releases. Archives are named forkline-{version}-{target}.tar.gz (.zip on Windows):

Every release ships a SHA256SUMS.txt you can verify locally:

sha256sum -c SHA256SUMS.txt

Then unpack and move the binary onto your PATH:

tar -xzf forkline-<version>-<target>.tar.gz
sudo mv forkline-<version>-<target>/forkline /usr/local/bin/forkline

Each archive also contains shell completions (bash, zsh, fish, powershell, elvish) and a man page — see the Tarball releases tip under Shell completions.

Build from source

Requires Rust stable and protoc, and a checkout of the (private) Calypso repository:

cargo install --path crates/calypso-cli --locked

The binary is installed as forkline (not calypso-cli).

Verify the install

forkline --version

Platform notices

• macOS Gatekeeper — if macOS refuses the binary with “cannot be opened because it is from an unidentified developer”, run xattr -d com.apple.quarantine /usr/local/bin/forkline, or right-click the binary in Finder and choose Open.
• Windows SmartScreen — Windows may show “Windows protected your PC”. Click More info → Run anyway.
• Unsupported platforms — if no pre-built binary matches your platform, the npm package exits with an “Unsupported platform” error rather than building from source. Set FORKLINE_BINARY to point at a compatible binary, or open an issue on GitHub.

Shell completions

Installing the CLI puts the forkline binary on your PATH but does not enable shell completion automatically. Run forkline completions install once after installation; see forkline completions <shell> for details and per-shell options.

Authentication

First-time setup

forkline auth login

The CLI starts a browser-based sign-in: it prints a verification URL and short code, opens your browser when possible, and receives an API token automatically once you approve the request in the Forkline web app. The token is stored in your system keyring by default, or in a 0600-permissions file at ~/.config/forkline/credentials.toml if no keyring is available.

Without a browser

On SSH sessions or headless containers, skip the browser with --no-browser. The CLI prints the URL where you can create a Personal Access Token in the web UI (Settings → API Tokens) and waits for you to paste it:

forkline auth login --no-browser

Non-interactive login

Pipe a token via stdin:

echo "$FORKLINE_TOKEN" | forkline auth login --token-stdin

CI / headless environments

Set the FORKLINE_TOKEN environment variable. It takes priority over stored credentials:

export FORKLINE_TOKEN="fl_pat_v1_..."
forkline me

Profiles

The CLI supports named profiles for managing multiple accounts or environments:

forkline auth login --profile staging --api-url https://api.staging.forkline.dev/v1
forkline me --profile staging

The default profile is default with API URL https://api.forkline.dev/v1.

Quickstart

# Verify authentication
forkline me

# List repositories
forkline repo list

# View a specific repository
forkline repo view my-project

# List available runner sizes
forkline runner sizes

# Start a runner (consumes credits)
forkline runner start --repository my-project --size basic --wait

# List running runners
forkline runner list

# List routines
forkline routine list

# View analytics
forkline analytics overview

# Manage secrets (value via stdin, never argv)
echo "my-secret-value" | forkline secret set DB_PASSWORD --repository my-project --value-stdin

# Browse the MCP catalog and connect a server
forkline mcp catalog list --search grafana
forkline mcp create --from-catalog context7 --credential CTX7_KEY=account/CTX7_KEY --repository my-project --enable

# Create a token (shown once)
forkline token create --name "ci-token" --scopes "runners:read,runners:write"

Warning: Starting a runner consumes billing credits. Use forkline billing credits to check your balance.

Command reference

forkline auth

forkline me

Display the authenticated user’s profile.

forkline repo

forkline runner

forkline routine

<ref> is a routine name, UUID or id prefix. Arguments written <file|ref> take a routine file when the path exists, otherwise a ref.

new writes a local file only and never overwrites without --force (exit 6). validate, test, backtest, events and runs change nothing and work with a token that has only the routines:read scope. Every command accepts the global --json flag. With --json, list prints {"routines": [...]}, and run --wait prints the run response plus a tasks array (only when at least one task started).

forkline mcp

Manage MCP servers: browse the catalog, create and switch servers on and off, and store the credentials they reference. mcps and servers are aliases for mcp; cat is an alias for catalog.

The catalog and server endpoints are only available to accounts with MCP enabled. Without it those endpoints return 404 and the CLI reports that the resource was not found; forkline mcp secrets is not gated.

view, get and show are interchangeable verbs, ls for list, new/add for create, edit for update, rm/remove for delete. Servers are addressed by Server ID (slug) or UUID; a Server ID that matches more than one server is reported as ambiguous rather than guessed.

Catalog browsing

catalog list shows two groups, Verified first and then Unverified, with no filters. A server that cannot run on Forkline appears only in a search, with a not available: <slug> — <reason> line.

--sort is refused unless you pass --all. The server pages by keyset (group, then title) and after continues that order, so sorting one page locally would not match the cursor you would use for the next one. Ties keep the server’s order, which makes repeated runs byte-identical.

forkline mcp catalog list --search postgres
forkline mcp catalog view context7

Servers

forkline mcp create --from-catalog context7 \
  --credential CTX7_KEY=account/CTX7_KEY \
  --repository 'acme/*' --enable
cat mcp.json | forkline mcp create --file - --server grafana
forkline mcp list --status failing
forkline mcp preview --repository acme/api
forkline mcp view context7 --repositories
forkline mcp upgrade context7 --to-version 3.3.0 --dry-run
forkline mcp disable context7

The status says whether a server runs, never how it was applied. unavailable means a problem on our side (“Not running on this repository right now. This is on our side and we’ve been alerted.”). A server that is incomplete is saved off and reads needs_setup; enable it once its required inputs and credentials are filled in.

With no --repository, a server targets every repository you own. The server evaluates owner/name globs per repository, so the CLI cannot say locally which repositories a glob will match: use view --repositories (one server) or preview (one repository).

--credential takes a reference to a stored secret, never a value. The binding is NAME=account/<SECRET> or NAME=repo/<SECRET>, and the secret name must be ^[A-Z_][A-Z0-9_]*$. The env:VAR form that appears inside an install plan is a placeholder the runner resolves, not a binding; the CLI rejects it with that explanation rather than letting the API reject it later. --input values are sent in the request body and may appear in logs, so keep anything secret out of them. When --file finds a literal secret-looking value in the pasted JSON, the CLI warns on stderr; store it with secrets set and bind it with --credential.

preview prints one row per server that applies to the repository. The table also lists the read-only servers from OpenCode settings and the repository settings, marked read only (and replaced by <server> when a server above overrides one); -o json and -o jsonl print the whole view (servers, raw, warnings). It reports on stderr any warning: <server>: <message>, for example a declared credential that has no stored value.

Account credentials

pass show personal/grafana/token | forkline mcp secrets set GRAFANA_TOKEN --value-stdin
forkline mcp secrets set GRAFANA_TOKEN --value-env GRAFANA_TOKEN
forkline mcp secrets list
forkline mcp secrets describe GRAFANA_TOKEN --description "Grafana viewer token"
forkline mcp secrets delete GRAFANA_TOKEN

secrets set reads the value from stdin (--value-stdin), from a named environment variable (--value-env <VAR>), or by prompting on a terminal. There is no --value flag: command-line arguments are visible to any process through ps(1) and /proc/<pid>/cmdline, and for the whole lifetime of the process in some configurations. Non-interactive use without --value-stdin or --value-env is refused. A trailing newline from a pipe is stripped.

secrets describe is the one command to be careful with: it is implemented as PATCH /me/secrets/{name}, and the description it sends replaces the stored one. forkline mcp secrets describe GRAFANA_TOKEN --description "…" sets it; forkline mcp secrets describe GRAFANA_TOKEN with no --description prints the metadata and clears the stored description. For a read-only listing use secrets list.

secrets list shows names and when each was last rotated. Values are write-only — the API stores them in Vault and no read endpoint returns them. Deleting a credential leaves the servers that reference it in place; they read needs_setup until it is provided again.

forkline model

forkline connector

forkline analytics

All analytics subcommands accept --from and --to (YYYY-MM-DD).

forkline secret

forkline token

forkline provider

Routine definitions

Routines are defined as YAML (or JSON) files. Create or update them with forkline routine create --file <path> / forkline routine update <ref> --file <path>, or sync a directory with forkline routine push [PATH] (defaults to .forkline/routines/). A file ending in .json is read as JSON, anything else as YAML. name and description sit beside the spec fields:

name: weekly-deps
description: Update dependencies every Monday
on:
  schedule:
    cron: "0 6 * * 1"
    timezone: Europe/Berlin
repositories:
  include:
    - name: "acme/*"
agent:
  prompt: Update outdated dependencies in {{ repository.fullName }} and open a PR.

The same routine as JSON:

{
  "name": "weekly-deps",
  "on": { "schedule": { "cron": "0 6 * * 1", "timezone": "Europe/Berlin" } },
  "repositories": { "include": [{ "name": "acme/*" }] },
  "agent": { "prompt": "Update outdated dependencies in {{ repository.fullName }} and open a PR." }
}

on takes exactly one of events, schedule and webhook. The Routines guide (not published yet) covers events, filters, the when condition, template variables, repositories, agent settings and limits.

A typical loop is forkline routine new --example review-prs, edit the file, forkline routine validate <file>, forkline routine backtest <file>, forkline routine test <file> --event <id>, then forkline routine push --publish. Use forkline routine pull to download routines that were created elsewhere.

If the server rejects a definition, the CLI prints one line per problem as file:line: message (pointer) (file: message (pointer) when the line is unknown), and exits with code 2:

routine.yaml:9: Unknown field `inlcude`. Allowed here: `include`, `exclude`. Did you mean `include`? (/filters/labels/inlcude)

Custom webhook secrets

A routine with on.webhook and a token or preset: forkline gets a secret when it is created. The CLI prints it once, with a notice that it will not be shown again; store it then. For preset: github and preset: sentry the sender holds the secret: store it with forkline routine webhook <ref> --set-secret secret.txt (or - for stdin). Forkline never shows it back. Use forkline routine webhook <ref> to print the webhook URL, the authentication method (for a token, the header name too, so a custom header is not mistaken for Authorization) and whether a secret is configured and where it came from, and forkline routine webhook <ref> --rotate-secret to replace a generated secret (the old one stops working at once; it asks for confirmation, or pass --yes in scripts). The flags exclude each other.

forkline billing

forkline config

forkline completions <shell>

Generate shell completions. Supported shells: bash, zsh, fish, powershell, elvish.

The command prints a completion script to stdout. You must install it into your shell’s completion directory — installing the CLI does not enable shell completion automatically.

forkline completions install

forkline completions install zsh

zsh

Choose one of the following methods.

Option 1 — oh-my-zsh (recommended if you use oh-my-zsh):

mkdir -p "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/completions"
forkline completions zsh > "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/completions/_forkline"
exec zsh

Option 2 — plain zsh (user directory, no root required):

mkdir -p ~/.zfunc
forkline completions zsh > ~/.zfunc/_forkline

Then add these two lines to your ~/.zshrc in this order — fpath must be updated before compinit runs:

fpath=($HOME/.zfunc $fpath)
autoload -Uz compinit && compinit

If completions still do not appear after restarting your shell, clear the completion cache and restart:

rm -f ~/.zcompdump*
exec zsh

Option 3 — system-wide (requires sudo):

forkline completions zsh | sudo tee /usr/local/share/zsh/site-functions/_forkline >/dev/null

bash

System-wide (requires bash-completion and sudo):

forkline completions bash | sudo tee /etc/bash_completion.d/forkline >/dev/null

Per-user (loaded automatically by bash-completion):

mkdir -p ~/.local/share/bash-completion/completions
forkline completions bash > ~/.local/share/bash-completion/completions/forkline

Per-user (appended to .bashrc):

forkline completions bash >> ~/.bashrc
source ~/.bashrc

fish

mkdir -p ~/.config/fish/completions
forkline completions fish > ~/.config/fish/completions/forkline.fish

powershell

forkline completions powershell

Add the output to your PowerShell profile. Run echo $PROFILE to find its location.

elvish

forkline completions elvish

Add the output to your Elvish configuration (typically ~/.config/elvish/rc.elv).

forkline man

Generate a man page (roff format) to stdout:

forkline man > ~/.local/share/man/man1/forkline.1

forkline schema

Print a machine-readable JSON description of the entire CLI command tree, generated directly from the CLI’s own parser definitions. Requires no authentication, network access, or configuration file. Useful for tooling and AI agents that want to discover exact command/argument names, types, defaults, environment variables, and conflicts without parsing human help text:

forkline schema

The document is versioned independently of the CLI release (schema_version), so consumers should check that field before relying on the structure.

forkline agent-guide

Print a machine-readable JSON guide intended for AI coding agents operating the CLI: a catalog of top-level commands (with auth requirements and subcommands), output-format conventions, non-interactive flags, destructive-operation names, exit codes (including partial bulk failure), and general tips. Requires no authentication:

forkline agent-guide

Output modes

Control output with --output (or FORKLINE_OUTPUT):

-o is the short form of --output. --json is a global shorthand for --output json; it wins over FORKLINE_OUTPUT but cannot be combined with an explicit --output or -o. With --json, an error is also printed to stdout as {"error": {"kind", "code", "message", "http_status", "request_id", "retry_after_seconds", "issues"}}, and the exit code still tells you what failed.

stdout / stderr contract: Data output goes to stdout. Progress messages, prompts, and errors go to stderr. This allows piping data output while still seeing errors.

# Pipe JSON to jq
forkline repo list --output json | jq '.items[].name'

# Collect IDs only
forkline runner list --output quiet > runner-ids.txt

Exit codes

Changes

Breaking changes to the CLI, for scripts written against earlier versions:

• forkline runner settings set takes its JSON in --settings (it was --json). --json is now the global output flag.
• --json is a global flag for every command, the same as --output json. -o is the short form of --output.
• forkline routine list --json prints {"routines": [...]}.
• forkline routine new writes a local scaffold and is no longer an alias of routine create. create keeps the alias add.
• forkline routine run --wait --json prints the run response with a tasks array of the final task states, only when at least one task started.
• Responses are decoded strictly: an unknown value or a missing field exits with code 1 and failed to decode response, instead of being tolerated. --json on the routine commands that print the server document as is (runs, events, event, test, backtest, new --from-event) prints it even when this CLI cannot decode it.

Custom provider import

Import a custom AI provider from JSON using forkline provider import --file <path>:

{
  "provider": {
    "my-provider": {
      "name": "My Custom Provider",
      "npm": "@ai-sdk/example",
      "models": {
        "model-1": {
          "name": "Model 1",
          "contextWindow": 128000,
          "modalities": {
            "input": ["text"],
            "output": ["text"]
          }
        }
      },
      "options": {
        "baseURL": "https://api.example.com/v1"
      }
    }
  }
}

Note: baseURL must be nested under options; the API rejects a top-level baseURL field. contextWindow uses camelCase (matching the API); the snake_case form context_window is also accepted for convenience. Exactly one provider may be included per import file.

OpenCode configuration

Manage a repository’s OpenCode configuration with forkline repo opencode-config:

# View current OpenCode config
forkline repo opencode-config get my-repo

# Set OpenCode config from a file
forkline repo opencode-config set my-repo --file opencode-config.json

# Set OpenCode config from stdin (use --file -)
echo '{"instructions":["Be helpful"]}' | forkline repo opencode-config set my-repo --file -

# Delete OpenCode config (requires --yes when non-interactive)
forkline repo opencode-config delete my-repo --yes

The config is a free-form JSON object validated against the bundled OpenCode settings schema; the keys permission, autoupdate, model, and provider are reserved for the platform and rejected. Allowed keys include logLevel, mcp, and instructions, for example:

{
  "logLevel": "INFO",
  "mcp": {},
  "instructions": ["Be helpful"]
}

Safety and confirmations

Destructive operations (delete, stop, revoke) prompt for confirmation in interactive mode. In non-interactive mode (piped stdin or --no-input), these commands require --yes:

forkline runner stop my-runner --yes
forkline token revoke old-token --yes

The --no-input flag (or FORKLINE_NO_INPUT=true) disables all interactive prompts. Combined with --yes, it allows fully scripted usage.

Environment variables

Troubleshooting

Enable debug logging with FORKLINE_LOG=debug for detailed request/response traces.