CLI reference

Every railcode command, grouped by what it operates on: apps, storage, agents, data, connectors, and organization administration.

npm install -g railcode@latest      # or: pnpm add -g railcode@latest
railcode --version

Configuration

The CLI stores its selected instance, organization, and personal token at ${RAILCODE_HOME:-~/.railcode}/config.json.

API-URL resolution for every command: --api-url flag → RAILCODE_API_URL → saved config → https://api.railcode.app.

RAILCODE_API_TOKEN overrides the saved token. On a 401, the saved token is cleared and you are asked to log in again.

A CI runner has no saved config at all, so the token alone is not enough. Set all three: RAILCODE_API_TOKEN, RAILCODE_API_URL, and RAILCODE_ORG_UUID. Without the last one the command stops at "No organization on file" despite a valid token. Only the token is a secret; the other two are identifiers.

--json is available on most read commands. railcode <command> --help prints the full current flag set.

Auth

railcode login [--api-url <url>] [--paste|--no-browser]
railcode login --setup-token <rc_setup_...>

Browser-based. --paste skips the localhost callback for SSH or headless machines. --setup-token is the one-time, no-browser onboarding path that the dashboard mints. It is valid for about 10 minutes.

Apps

railcode init <app> [dir] [--template hono+vite|hono+static|tanstack|static]
railcode dev [--port <n>] [--reset]
railcode deploy [--private] [--no-source] [--force]
railcode pull [<deploy>] [--app <slug>] [--dir <path>] [--force]

railcode apps list [--archived|--all]
railcode apps show <app>              # your role, can edit, can manage
railcode apps show <app> --json       # includes `generation`
railcode apps access <app>
railcode apps set-access <app> --mode organization|private|restricted [--members …] [--editors …]
railcode apps add-editor <app> <email>
railcode apps remove-editor <app> <email>
railcode apps add-viewer <app> <email>       # restricted mode only
railcode apps remove-viewer <app> <email>
railcode apps transfer <app> --to <email|uuid>
railcode apps archive <app>
railcode apps unarchive <app>
railcode apps delete <app> [--yes]

apps delete is irreversible and removes deploys and app data. archive is the reversible alternative. An archived app keeps serving at its host, keeps its slug, keeps its data, and keeps running its agents. It only drops out of the launcher.

Manifest and secrets

railcode manifest validate [path]
railcode manifest show <app>

railcode secrets set NAME          # hidden prompt, or piped on stdin
railcode secrets import [.env]
railcode secrets ls                # names + set-at + digest, never values
railcode secrets rm NAME

App storage

Reads and writes the deployed app's stores. Requires an owner grant or an org admin with app:manage_any. An editor gets a 403.

railcode app kv collections
railcode app kv list <collection> [--query '[["stage","eq","won"]]'] [--limit 20] [--count]
railcode app kv get <collection> <key>
railcode app kv set <collection> <key> '{"n":1}'      # or --file value.json
railcode app kv delete <collection> <key>
railcode app kv drop <collection> [--yes]

railcode app files list
railcode app files download <name> [--out <path>]
railcode app files upload <path> [--name <remote-name>]
railcode app files delete <name>

Scope with --scope shared|user|role (default shared; user and role need --user <uuid> / --role <uuid>). --scope all lists every scope with owner attribution, but only for the listings. A mutation must name one scope.

kv list paging uses --limit <n> with --offset <n> as a whole multiple of --limit.

Logs

railcode logs app --app <slug> [--follow]        # invocations
railcode logs app <invocation_id> --app <slug>   # one full trace

Per-app backend logs, available to people with edit rights. Kept about 14 days.

Org-wide streams are admin-only and capability-gated:

railcode logs <connector|service-connector|llm|email|agent> [filters]
railcode logs <stream> <request_id>

Stream	Capability
`connector`	`connection:manage`
`service-connector`	`service-connector:manage`
`llm`	`llm:manage`
`email`	`email:manage`
`agent`	`agent:manage`

Filters: --app, --user, --connector, --agent, --source app|agent (LLM only), --status, --limit <1..500> (default 100).

CI and tokens

railcode ci github [--app <slug>] [--repo <owner/name>] [--branch <name>] [--no-secret] [--force]

railcode token create [--app <slug>] [--name <label>] [--expires-in-days <n>]
railcode token list   [--app <slug>]
railcode token revoke [--app <slug>] <token-prefix>

Agents

railcode agent list
railcode agent show <agent> [--manifest]
railcode agent pull <agent> [--output agent.json]
railcode agent create --file agent.yaml [--visibility org|personal]
railcode agent update <agent> --file agent.yaml [--visibility org|personal]
railcode agent delete <agent> [--yes]
railcode agent test --file agent.yaml --input '{"k":"v"}' [--trace]
railcode agent run <agent> --input '{"k":"v"}' [--trace]

railcode agent schedule show <agent>
railcode agent schedule set <agent> --cron "0 9 * * *" --timezone UTC
railcode agent schedule add|update <agent> [--name] [--cron] [--timezone] [--enabled|--disabled]
railcode agent schedule pause|resume <agent>
railcode agent schedule run-now <agent> [--trace]
railcode agent schedule delete <agent> [--yes]

Aliases: list=ls, show=get, pull=export, update=edit, delete=rm, run=invoke, agent=agents.

--file accepts JSON or YAML (the parser is picked by extension). pull and show --manifest emit JSON only.

run and test take --input '<json>' or --input-file <path>, never both. The default input is null. A runtime failure can still exit 0, so inspect the run status rather than $?.

Data and queries

Org-scoped: these work right after login, with no app and no railcode.json.

railcode db list
railcode db query "select 1"
railcode db query "select * from orders where total > $1" --params '[100]'
railcode db query --file report.sql --connection analytics

railcode query list
railcode query run my_orders --params '{"region":"emea","limit":5}'

db query --params takes a positional array. query run --params takes a named object.

Connectors

railcode connector list
railcode connector catalog                     # providers you can link
railcode connector docs <name> [--openapi]
railcode connector fetch "<path>" --connector <name> [--method <verb>] [--body|--file]
railcode connector tools <name>
railcode connector call <name> <tool> --args '{"…":"…"}'

railcode connector link <provider> [--no-wait]
railcode connector relink <name>
railcode connector add-mcp <name> <https-url>
railcode connector access <name> organization
railcode connector share <name> --user <email> | --role <name>

You own what you link, and it starts restricted. railcode personal-connectors was removed in CLI 0.3.0. Personal connectors were folded into railcode connector.

LLM gateway

railcode llm providers        # configured providers, each with its models
railcode llm models           # flat list of every callable model

Keys and cost rates are never shown.

Design system

railcode design-system                          # print the org's guidance (markdown)
railcode design-system set --file brand.md      # admin with design-system manage
cat brand.md | railcode design-system set
railcode design-system set --markdown "# Brand ..."

set reads from exactly one source, preferred in this order: --file, --markdown, piped stdin. An empty file or pipe is refused rather than silently wiping the guidance. Clear it deliberately with --markdown="".

Organization administration

See administration for members, roles, connections, connector --admin, query create, and analytics.

Migration

railcode migrate [--app <slug>] [--yes]

One-way and irreversible. See legacy.

On this page