The gateway CLI

gateway builds, publishes, seeds, serves and runs worlds from a terminal. One command talks to one project on your Surface Area host, so anything the CLI does is also visible in the dashboard and reachable over the REST API.

Install the command from npm

The CLI ships in the TypeScript SDK package, @withgateway/sdk. It needs Node.js 18 or newer.

npm install -g @withgateway/sdk
gateway --help

To skip the global install, run npx @withgateway/sdk gateway <command>, or add the package as a dev dependency and call npx gateway. gateway auth login writes the host and key pair to ~/.gateway/config.json with owner-only permissions. Generate the key pair under Project Settings → API keys; the world, session or version you create lands in the project those keys belong to.

gateway auth login \
  --host https://withgateway.ai \
  --public-key "$GATEWAY_PUBLIC_KEY" \
  --api-key "$GATEWAY_SECRET_KEY"

gateway auth status
gateway auth logout   # forget the stored credentials

Pass the secret key through an environment variable or a secrets manager, as the example above does. A key typed on the command line lands in your shell history.

Credentials resolve in a fixed order

Every command looks for a host and a key pair in three places and stops at the first that answers.

Order	Source	Notes
1	Flags on the command	`--host` on every command; `secret`, `agent list`, `release gate` and `traces import` also take `--api-key`.
2	Environment variables	`GATEWAY_HOST`, `GATEWAY_PUBLIC_KEY`, `GATEWAY_SECRET_KEY` (both CLIs accept `GATEWAY_API_KEY` as an alias for the secret key).
3	`~/.gateway/config.json`	Written by `gateway auth login` in either CLI. Set `GATEWAY_CONFIG_DIR` to keep it somewhere else.

Use environment variables in CI, where no login step runs:

export GATEWAY_HOST="https://withgateway.ai"
export GATEWAY_PUBLIC_KEY="pk-lf-..."
export GATEWAY_SECRET_KEY="sk-lf-..."

A missing host or key pair fails immediately and names which one is absent, instead of sending an unauthenticated request.

The schema runtime runs locally when Python is there

Compiling a world’s contract, serving its API and capturing from a vendor all run the schema runtime: stdlib-only Python that the npm package carries alongside dist/. Any python3 at version 3.12 or newer on your PATH runs those files exactly as the platform does, with no pip step and no PyPI download. Without such an interpreter, the same commands post the same request to the platform, which runs the identical code and returns the result. The difference is whether gateway worlds serve binds a local port or opens a hosted session.

Variable	What it does
`GATEWAY_PYTHON`	Name or path of the interpreter to use instead of probing `python3` and `python`.
`GATEWAY_RUNTIME`	`auto` (default), `local` to refuse the hosted fallback, or `platform` to always use it.
`GATEWAY_RUNTIME_PATH`	Directory holding the bundled runtime, when it is not beside `dist/`.

GATEWAY_RUNTIME=local turns the fallback into an error. Use it in CI so a build fails when the local runtime is missing.

Output is JSON unless a command says otherwise

Most commands pretty-print the platform’s JSON response to standard output, ready to pipe into jq. A few print a human summary instead and take --json to switch: worlds create, worlds schema templates, worlds schema describe, worlds test, worlds session list, worlds sandbox list and release gate. Commands whose output is already JSON accept --json and ignore it. A flag value may start with a dash (--content "-- x"); a token is read as a flag only when it names one of that command’s flags. Four commands write a stream rather than a document. worlds session export prints JSONL, one call per line; worlds data extract prints tagged JSONL with a summary on standard error; traces export prints one trace per line; files cat prints a file’s bytes. Any command that takes a local file takes drive:<path> for a file in the project’s drive, and --to <path> on worlds data calls pull, worlds data extract and worlds session export lands the output there.

Exit codes tell CI what happened

Code	Meaning
`0`	The command did what it was asked.
`1`	The platform refused the request, or the command’s own gate failed — a failing world test, a run below `--min-score`, a task whose entities do not exist.
`2`	The command could not run as given: bad arguments, an unknown subcommand, missing credentials, or rows and batch lines the world’s contract refused.

Commands that treat 2 as “refused, not broken” say so in their own --help: worlds data import, worlds data check and worlds create --batch.

A request with no answer stops after two minutes

Every request to the platform — from the CLI and from the TypeScript and Python SDKs — gives up after 120 seconds without an answer. The command then exits 1 with one line naming the cause, such as connection refused, DNS lookup failed or a timeout, instead of hanging. Set GATEWAY_TIMEOUT_MS to change the budget, in whole milliseconds:

export GATEWAY_TIMEOUT_MS=300000   # five minutes

Any other value (zero, negative, not a number) is refused. worlds sandbox requests keep their own 660-second budget.

Print a packaged skill for an agent

Five agent-readable guides ship inside the package. gateway worlds skill <name> prints one to standard output; --install <repo> writes it, plus any agent it ships, into that repository’s .claude/ directory. gateway skill search <words> finds the guide for a topic by its description and section headings.

gateway worlds skill --list
gateway skill search benchmark harbor
gateway worlds skill worlds-getting-started
gateway worlds skill world-data-ingestion --install .

Skill	What it teaches an agent
`worlds-getting-started`	Building a world end to end: auth, contract, data, push, session, run, iterate.
`benchmarks-getting-started`	A benchmark is a world with tasks: init, check, push, run k rollouts per model, results; when a harbor or verifiers tree stays on the runner.
`world-data-ingestion`	Putting rows into a world, the rows file contract, batches and refusals.
`connector-schema-authoring`	Authoring a connector template against the `gateway-world/1` contract.
`hooks-getting-started`	Rules around an agent’s tool calls from one `gateway-hooks.toml`: aliasing, redaction, per-task overrides, `gateway hooks check`.

gateway worlds connector skill is an alias for the connector one. --force overwrites an installed copy whose content has drifted.

The command groups

Group	What it covers	Page
`gateway worlds`	Build, seed, serve, test and run worlds; connectors, contracts, data, sessions and stored tasks	worlds
`gateway bench`	Worlds as versioned bundles: push, pull, branches, tags, proposals, hosted runs	bench & versions
`gateway environment`	Reads over a world’s rollouts, per-task performance and linked scenario set	Worlds client
`gateway auth`	Store and inspect the credentials above	this page
`gateway secret`	Project secrets, write-only: `set`, `list`, `delete`	—
`gateway files`	The project’s file drive: upload, list, get, download, cat, delete, move, mkdir, fetch a URL, sync connectors	files
`gateway traces`	List, get and export traces, observations and trace sessions; `traces import` posts OTLP/JSON exports	traces
`gateway dashboards`	Design dashboards as code: create, pull, push, test a transform, render, open	dashboards
`gateway release`	`release gate` turns a release gate’s verdict into an exit code	Core Resources
`gateway hooks`	Rules around an agent’s tool calls (`gateway-hooks.toml`): `check` validates and dry-runs a file, `run` is the command a coding agent names as its hook	Hooks, coding agents

gateway algorithm, gateway deploy and gateway init belong to the Python package — see the Python SDK overview.

Where to go next

worlds — every gateway worlds subcommand, grouped by workflow.
bench & versions — pushing bundles, and how slug@ref pins resolve.
files — the drive from the terminal, and drive:<path> in worlds data commands.
traces — reading and exporting traces, and importing OTLP.
dashboards — a design dashboard’s render code in a local directory: edit, push, render.
Getting started with worlds — the same steps as a narrative.

CLI

Python SDK

TypeScript SDK

SDK Reference

REST API

MCP Server

Install the command from npm

Credentials resolve in a fixed order

The schema runtime runs locally when Python is there

Output is JSON unless a command says otherwise

Exit codes tell CI what happened

A request with no answer stops after two minutes

Print a packaged skill for an agent

The command groups

Where to go next

​Install the command from npm

​Sign in once per machine

​Credentials resolve in a fixed order

​The schema runtime runs locally when Python is there

​Output is JSON unless a command says otherwise

​Exit codes tell CI what happened

​A request with no answer stops after two minutes

​Print a packaged skill for an agent

​The command groups

​Where to go next

Install the command from npm

Sign in once per machine

Credentials resolve in a fixed order

The schema runtime runs locally when Python is there

Output is JSON unless a command says otherwise

Exit codes tell CI what happened

A request with no answer stops after two minutes

Print a packaged skill for an agent

The command groups

Where to go next