One command to wire up your agent.

Quickstart

npx layerx1

That is the whole thing. The wizard:

Picks your tools — arrow keys and space, with a live installed / not installed mark against each one.
Installs what’s missing — the exact command is shown and you approve it. Anything already installed is skipped.
Chooses your models — read live from the gateway, grouped by tier with context window and price. A primary, any number of secondary models, and a small/fast one.
Takes your key — masked input, written only to the tools you picked.
Writes and verifies — one real request confirms the gateway answers before you leave.

Or do it in one non-interactive line — handy for scripts and dotfiles:

npx layerx1 setup \
  --key lx1_your_key \
  --tool claude-code,codex \
  --model lx1-deepseek-v4-flash \
  --fallback lx1-opus-5,lx1-qwen3-coder-480b

--tool all configures every supported tool at once. Add --install --yes to install the missing ones too.

The CLI is zero-dependency, needs Node 18+, and never sends your key anywhere except into your own local config files. Point it at a different gateway with --url (default is the hosted gateway).

Piped or in CI, npx layerx1 --key lx1_… runs the same steps deterministically — the tools already on the machine plus the catalog’s recommended models — because there is no TTY to prompt on. Without a key it points you at setup instead of prompting into a void.

The model catalog is dynamic

Model ids are not compiled into the CLI. Each run resolves the catalog live from GET /v1/models, caches it at ~/.layerx1/catalog.json for six hours, and falls back to a bundled snapshot only when there is no network. A model added to Layer X1 therefore appears in the picker — and in Codex’s declared context window — with no CLI release. Use --refresh-catalog to bypass the cache, or --offline to never touch the network.

Setup commands

Command	What it does
`npx layerx1` · `npx layerx1 init`	The interactive wizard: tools → install → models → key → verify.
`npx layerx1 setup --key <k> [--tool <ids>]`	Configure one or more tools non-interactively.
`npx layerx1 install [--tool <ids>]`	Just install the tools, skipping anything already present.
`npx layerx1 status`	Which tools are installed, and which are pointed at Layer X1.
`npx layerx1 doctor`	Environment, per-tool install paths, and where the catalog came from.
`npx layerx1 models [--json]`	List the model catalog with tier, context window, and pricing.
`npx layerx1 test [--key <k>]`	Send one real request and print the reply. Without `--key` it reuses `LAYERX1_API_KEY`, the Codex bearer token, or the key already written to Claude Code’s settings.
`npx layerx1 unset [--tool <ids>]`	Remove the config the CLI added (previous files are kept as timestamped backups).
`npx layerx1 --version`	Print the CLI version.

Agent-run commands

The same binary is a client for the agent-native API — useful for submitting and following a run without writing any code.

Command	What it does
`run create --model <m> [--input <t>] [--budget <usd>] [--mode exact\|auto]`	Create a run. With `--model` and `--input` the gateway executes it.
`run inspect <runId>`	Show the run record.
`run follow <runId>`	Tail the run’s event stream over SSE.
`run cancel <runId> [--reason <r>]`	Cancel a run.
`run replay <runId>`	Re-fetch the run and its events for inspection.
`plan explain <runId>`	Show the plan the run was executed under, where the run carries one.
`state create [--value <json>] [--file <path>]`	Create a durable state handle.
`state append <id> --delta <json> \| --file <path>`	Append a delta.
`state get <id>`	Read the current snapshot.
`artifact upload --file <p> \| --text <s> [--schema <s>] [--exact]`	Upload an artifact.
`artifact query <id> [--filter field:op:value] [--limit N] [--search s]`	Query it.
`artifact inspect <id>`	The compact descriptor — never raw bytes.
`artifact delete <id>`	Delete it.

Submit a run and watch it

npx layerx1 run create --model lx1-gpt-oss-120b --input "Summarize CHANGELOG.md" --budget 0.25
npx layerx1 run follow run_123

--exact on an upload asserts the artifact is a lossless projection of its source; without it, provenance records that the content may be lossy. See Artifacts.

Flags

Flag	Default
`--key <k>`	— (required for `setup`)
`--url <u>`	`https://api.layerx1.com`
`--model <m>`	the catalog’s recommendation (`lx1-deepseek-v4-flash` today)
`--fallback <ids>`	Secondary models to also make available, comma-separated. Aliases: `--models`, `--extra-model`.
`--small-model <m>`	the catalog’s recommendation (`lx1-glm-4.7-flash` today) — the background/small-task model, where a tool has a separate slot for one
`--tool <ids>`	comma-separated, or `all`
`--install` / `--no-install`	Also install any selected tool that is missing / never install anything.
`--yes`, `-y`	Accept every prompt, including running a vendor’s install script.
`--refresh-catalog`	Ignore the cached catalog and re-fetch `/v1/models`.
`--offline`	Never touch the network: use the cached or bundled catalog and skip verification.
`--print`	Print the config instead of writing files. Writes nothing at all, not even a cache.
`--persist-key` / `--no-persist-key`	Also save `LAYERX1_API_KEY` for shells/scripts / never touch your env or shell profile. Codex does not need the env var.
`--home <dir>`	Write configs under `<dir>` instead of your home directory (sandboxes, tests). Also settable via `LAYERX1_HOME`.
`--ascii`	Plain-ASCII output for consoles that can’t render block glyphs. Also `LAYERX1_ASCII=1`.

Secondary models

The gateway has no client-side “fallback model” parameter, so --fallback does not pretend otherwise. Each tool receives your extra picks in a slot it genuinely has:

Tool	Where secondary models land
Codex CLI	One entry per pick in `~/.codex/model-catalogs/layerx1.json`, each with its own context window — so `/model` switches between them.
Continue	One entry per pick in the `models:` list; the primary is first, so it is the default.
Aider	`weak-model` = your small/fast model, `editor-model` = your first extra pick.
Claude Code	Three model slots exist (opus/sonnet/haiku), so extras are surfaced as a `/model <id>` hint rather than invented into config.
Hermes	One `default_model` per provider, so extras are noted — they work through the same provider.
Cline / Cursor / Windsurf	Every id is printed for you to paste into the app.

Installing the tools

The CLI detects each tool by executable on PATH first, then by its config or extension directory, and reports which signal it used. Already installed means skipped. Where a vendor only ships a curl … | bash installer, that downloads and executes a remote script — the CLI labels it as such, prints the exact command, and runs nothing until you agree (or pass --yes). Desktop apps (Cursor, Windsurf) are never fetched: the CLI prints the download link. npx layerx1 doctor lists the install command it would use for each tool on your platform.

Supported tools

--tool accepts claude-code, codex, hermes, aider, continue, cline, cursor, cursor-cli, windsurf, antigravity, kiro — or all. Aliases: agy → antigravity, kiro-cli → kiro, cursor-agent → cursor-cli, hermes-agent → hermes.

Tool	What the CLI does
Claude Code	Writes the `env` block in `~/.claude/settings.json` — base URL, auth token, model tiers. See Claude Code.
Codex CLI	Writes `~/.codex/config.toml` (top-level keys + `model_catalog_json` + provider table with `experimental_bearer_token`) and `~/.codex/model-catalogs/layerx1.json`. See Codex CLI.
Aider	Writes `~/.aider.conf.yml` on the OpenAI-compatible route, including `weak-model` and `editor-model`.
Continue	Adds one `openai`-provider entry per selected model to `~/.continue/config.yaml`, or prints the entries to merge when a config already exists.
Cline	GUI-only — prints the Base URL / API Key / Model to paste.
Cursor	GUI-only — prints the steps: paste the key as the OpenAI API key, override the OpenAI base URL, add `lx1-*` model ids. See Cursor.
Cursor CLI	Print-only — `agent` / `cursor agent` has no BYOK hook (Cursor Cloud only). Setup prints the IDE override and a Hermes/Codex/Claude one-liner.
Windsurf	GUI-only — prints the steps for an OpenAI-compatible provider.
Hermes Agent	Writes `~/.hermes/config.yaml` (`providers.layerx1`, `model.provider: custom:layerx1`) and `~/.hermes/.env` (`LAYERX1_API_KEY`). See Other tools.
Antigravity (`agy`)	Print-only — custom endpoint is Gemini `generateContent`, which Layer X1 does not serve.
Kiro CLI	Print-only — no custom OpenAI-compatible provider; `chat.defaultModel` is Kiro’s catalog only.

Per-tool detail, and how to do each by hand, lives in the agent guides.

Safe by design

Deep-merge — it merges into your existing config; it never overwrites a whole file.
Managed blocks — additions are fenced with # >>> layerx1 … <<< markers, so they are easy to find and unset removes only what the CLI added.
Backups — every change writes a timestamped <file>.layerx1.bak-<timestamp> copy first.
Idempotent — re-running updates in place instead of duplicating, and it will not clobber a model you already set (it prints the value instead).

Your key for Codex

Codex gets the key from experimental_bearer_token in ~/.codex/config.toml. Setup does not require LAYERX1_API_KEY in the environment (Codex Desktop never sees User env vars). --persist-key still writes that variable for shells and scripts if you want it.

Verify it worked

npx layerx1 test

A successful run prints a model reply served from https://api.layerx1.com. If it fails, check npx layerx1 status and your key.

Get started

API reference

Agent-native API

Guides

Reference

One command to wire up your agent.

Quickstart

The model catalog is dynamic

Setup commands

Agent-run commands

Flags

Secondary models

Installing the tools

Supported tools

Safe by design

Your key for Codex

Verify it worked

​Quickstart

​The model catalog is dynamic

​Setup commands

​Agent-run commands

​Flags

​Secondary models

​Installing the tools

​Supported tools

​Safe by design

​Your key for Codex

​Verify it worked

Quickstart

The model catalog is dynamic

Setup commands

Agent-run commands

Flags

Secondary models

Installing the tools

Supported tools

Safe by design

Your key for Codex

Verify it worked