> ## Documentation Index > Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt > Use this file to discover all available pages before exploring further. # The gateway CLI > Install the gateway command from the @withgateway/sdk npm package, sign in to a project, and learn the conventions every subcommand shares — credentials, the local schema runtime, output, and exit codes. `gateway` builds, publishes, seeds, serves and runs [worlds](/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](/rest-api). ## Install the command from npm The CLI ships in the TypeScript SDK package, `@withgateway/sdk`. It needs Node.js 18 or newer. ```bash theme={null} npm install -g @withgateway/sdk gateway --help ``` To skip the global install, run `npx @withgateway/sdk gateway `, or add the package as a dev dependency and call `npx gateway`. ## Sign in once per machine `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. ```bash theme={null} 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: ```bash theme={null} 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:` for a file in the project's [drive](/cli/files), and `--to ` 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: ```bash theme={null} 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 ` prints one to standard output; `--install ` writes it, plus any agent it ships, into that repository's `.claude/` directory. `gateway skill search ` finds the guide for a topic by its description and section headings. ```bash theme={null} 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](/cli/worlds) | | `gateway bench` | Worlds as versioned bundles: push, pull, branches, tags, proposals, hosted runs | [bench & versions](/cli/bench) | | `gateway environment` | Reads over a world's rollouts, per-task performance and linked scenario set | [Worlds client](/sdk/environments) | | `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](/cli/files) | | `gateway traces` | List, get and export traces, observations and trace sessions; `traces import` posts OTLP/JSON exports | [traces](/cli/traces) | | `gateway dashboards` | Design dashboards as code: create, pull, push, test a transform, render, open | [dashboards](/cli/dashboards) | | `gateway release` | `release gate` turns a release gate's verdict into an exit code | [Core Resources](/rest-api/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](/hooks), [coding agents](/hooks/coding-agents) | `gateway algorithm`, `gateway deploy` and `gateway init` belong to the Python package — see the [Python SDK](/sdk) overview. ## Where to go next * [worlds](/cli/worlds) — every `gateway worlds` subcommand, grouped by workflow. * [bench & versions](/cli/bench) — pushing bundles, and how `slug@ref` pins resolve. * [files](/cli/files) — the drive from the terminal, and `drive:` in worlds data commands. * [traces](/cli/traces) — reading and exporting traces, and importing OTLP. * [dashboards](/cli/dashboards) — a design dashboard's render code in a local directory: edit, push, render. * [Getting started with worlds](/worlds/getting-started) — the same steps as a narrative. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.