> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerx1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# One command to wire up your agent.

> npx layerx1 walks you from nothing to a working agent: pick your tools, install what's missing, choose models from the live catalog, paste your key, verify. It deep-merges into your existing files, keeps timestamped backups, and is safe to re-run.

## Quickstart

```sh theme={null}
npx layerx1
```

That is the whole thing. The wizard:

1. **Picks your tools** — arrow keys and space, with a live *installed / not installed* mark
   against each one.
2. **Installs what's missing** — the exact command is shown and you approve it. Anything
   already installed is skipped.
3. **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.
4. **Takes your key** — masked input, written only to the tools you picked.
5. **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:

```sh theme={null}
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.

<Note>
  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).
</Note>

<Note>
  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.
</Note>

## 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](/api/agent-runs) — 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](/api/agent-runs#states).             |
| `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](/api/artifacts).                                |
| `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.                                                           |

```sh title="Submit a run and watch it" theme={null}
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](/api/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](/guides/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](/guides/codex). |
| **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](/guides/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](/guides/other-tools#hermes-agent).               |
| **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](/guides/other-tools).

## 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

```sh theme={null}
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.