# Commands

`writ` is one binary. It runs the control plane, `writ serve`, and the commands you use against one. Plans and applies run on the control plane.

```sh
writ [--dir DIR] [--env ENV] [--verbose] <command> [flags] [args]
```

## Commands

| Command | What it does |
| --- | --- |
| `writ import accept --imports FILE PLAN` | Accept the plan of an OpenTofu stack after `writ import bulk`: it passes when the plan changes nothing but listed provider-only settings and imports exactly the objects that `FILE`, which `writ import bulk` wrote beside the code, records, each at its address by its import id. `PLAN` is the plan file that `tofu plan -out` saved, which `writ import accept` reads with `tofu show -json` in `FILE`'s directory or `--dir`. A JSON plan, the masked plan document, the output of `writ plan --remote --json`, or the output of `tofu show -json`, passes only imports that plan no update. See [Import and accept](/docs/import-bulk#import-and-accept). |
| `writ import bulk SELECTION.json` | Take over many existing objects into an OpenTofu stack: write `resource` blocks that declare them, with references in place of literal ids, into one new file, `imported.tf` by default, and the objects it selected into `imported.imports.json`. It writes no state and plans nothing. `--type TYPE --id ID...` selects objects without a file. See [Import many objects](/docs/import-bulk). |
| `writ agent init` | Write the writ skill for an OpenTofu repository that Writ plans into `.agents/skills/writ` and a copy into `.claude/skills/writ`, and add a section to `AGENTS.md` that points to it. It changes nothing in `AGENTS.md` outside its own section. `--print` writes nothing and prints the files, and `--force` replaces skill files that differ. See [Set up a repository](/docs/agents#set-up-a-repository). |
| `writ mcp` | Serve Model Context Protocol tools on stdin and stdout for the OpenTofu stacks under `--dir`: `plan` asks the control plane to plan a commit, `get_plan`, `runs`, `drift`, `state_index`, and `policy` read what it keeps, `schema` reads provider schemas from Writ's cache at the versions `.terraform.lock.hcl` pins, and `import_accept` checks an import's plan. No tool applies or approves. `--allow-providers` adds `import_bulk`, which starts the stack's providers with the environment and credentials of `writ mcp`, and lets `schema` download a provider the cache lacks. See [The MCP server](/docs/agents#the-mcp-server). |
| `writ version` | Print the version. |
| `writ serve --config FILE` | Run the control plane. `--check` prints what each team can do and serves nothing. See [Run a control plane](/docs/run). |
| `writ serve --dev` | Run a control plane for this user alone, on loopback, with its store in SQLite under `$XDG_DATA_HOME/writ/dev`. `--data`, `--listen`, and `--database` change where it keeps its store and where it listens, and `--config FILE` takes `forge`, `repo`, `tofu`, and `policy` blocks and `poll_every`, in HCL. See [writ serve --dev](/docs/run#writ-serve---dev). |
| `writ plan --remote` | Plan an OpenTofu stack on the control plane, wait, and print the plan the server keeps. In a clean work tree of a [repository](/docs/repos) the control plane reads, send the commit it's on, which the control plane fetches; with edits, say why no commit can be planned. [How a CLI finds its control plane](/docs/sign-in#how-a-cli-finds-its-control-plane) gives the server and token it uses. Needs `--env`, except on the dev control plane. |
| `writ plan --remote --stack NAME --commit SHA` | Plan a commit and read no file, as a CI job with no checkout does. `--repo NAME` sets the repository, which a CI job's token already sets. |
| `writ repo add NAME FORGE/PROJECT` | Add a repository: the control plane reads its default branch with the Git host's read token and prints the stacks found. `FORGE` is a forge's name or host. `--path` sets the directory under which it finds stacks, and `--prefix` goes before each stack's name. Needs `admin` on every stack. See [Add a repository](/docs/add-repository). |
| `writ repo add [NAME] DIR` | Under `writ serve --dev`, add the local Git repository that contains `DIR`, such as `.`. |
| `writ repo list`, `writ repo show NAME` | Print the repositories with the last commit read and the last poll, or one repository and the stacks found at its head. |
| `writ ci gitlab --repo NAME` | Print the `.gitlab-ci.yml` lines that plan each served stack and environment of a repository in merge requests, approve them in a blocking manual job, and apply them after the merge, and the teams, grants, and approval rule the config needs, by the project's id. `--envs`, `--image`, and `--component` change them. |
| `writ ui` | Print the control UI's address. Under `writ serve --dev`, print a sign-in link that works once, for 10 minutes. |
| `writ show --remote ID` | Print a plan `writ serve` keeps, by its id or its ref, or a run, by its id. |
| `writ show --remote --request KEY` | Print the run that the apply request with the key started, or say that none did. A key with no run is closed, so no request with it starts one. `writ apply --remote` prints the key when it can't tell whether its run started. |
| `writ approve --remote ID` | Approve a plan another person created. `--withdraw` takes the approval back until the plan starts applying. See [Approve and apply a plan](/docs/apply). |
| `writ approve --remote --pipeline` | In a CI job, approve every live plan of the job's own pipeline, all or none. |
| `writ apply --remote ID` | Apply a plan `writ serve` keeps, once it has its approvals, and follow the run until it ends. `--override REASON` applies it without them, for a person with `override`. The first Ctrl-C stops following, and the run goes on. Each command sends one key, so its requests start one run at most, and asks whether the run started when an answer is lost. See [When an answer is lost](/docs/apply#when-an-answer-is-lost). |
| `writ apply --remote --merged --env ENV --stack NAME` | After a merge, apply the stack's approved plan with the same sources as the merged commit: the CI job's own commit on the default branch, or `--repo` and `--commit`. |
| `writ apply --remote --yes` | Plan as `writ plan --remote` does, and apply the plan when no approval rule needs one. |
| `writ runs --remote` | Print the runs `writ serve` started in `--env`, newest first, of `--stack` or of every stack. |
| `writ state adopt STACK --env ENV --version N --reason TEXT`, or `--serial N` for a stack on S3 | Seal a secret set with the newest state of an OpenTofu stack that has none, such as a state on S3 that an apply outside Writ wrote, so its plans can be approved again. It needs `adopt`, and a person's session. A secret the state contains where nothing marks it isn't learned. See [Adopt a state](/docs/adopt-state). |
| `writ login [URL]` | Sign in to a control plane through the team's identity provider, and keep a session, which lasts the control plane's `session_ttl`, 12 hours by default, in `~/.config/writ/sessions.json`, readable by you alone. When the identity provider offers the device flow, it prints a code to type at its page. When it doesn't, as on GitLab.com, it prints a URL to open in a browser on this computer, opens it when it can, and takes the identity provider's answer on a loopback port. `--device` and `--browser` force a flow. With no URL it signs in to the control plane that `--server` or `WRIT_SERVER` sets. `--issuer NAME` picks the identity provider when the control plane has several. See [writ login](/docs/sign-in#people-writ-login). |
| `writ logout [URL]` | End your session on the control plane and delete it from the session file. |
| `writ whoami` | Print the control plane and how it was found, who the token speaks for and where it came from, its teams, and its grants. It always asks the control plane, and accepts `--remote`. |

`plan`, `apply`, and `runs` without `--remote` are usage errors that name the remote form.

## Flags

| Flag | Commands | Meaning |
| --- | --- | --- |
| `--json` | every command but `serve`, `mcp`, `ci`, and `help` | Print one JSON document on stdout. With `--help` or `-h`, the usage text prints instead. See [JSON output](/docs/json-output). |
| `--out FILE` | `import bulk` | The new file to write in the stack, `imported.tf` by default. |
| `--imports FILE` | `import accept PLAN` | The file in which `writ import bulk` recorded the objects it selected, such as `imported.imports.json`. The plan must import exactly those. |
| `--type TYPE`, `--id ID` | `import bulk` | Select objects without a selection file: the type, and an import id to read. Repeat `--id` for each object. |
| `--provider ADDR` | `import bulk` | Read the objects through the provider configuration at `ADDR`. |
| `--max-objects N`, `--max-bytes N` | `import bulk` | Refuse to read more than `N` objects, 500 by default, or to write a file larger than `N` bytes, 1 MiB by default. |
| `--yes` | `apply --remote` | Plan as `writ plan --remote` does, and apply the plan when no approval rule needs one. |
| `--remote` | `plan`, `apply`, `approve`, `show`, `runs`, `state`, `whoami` | Run against `writ serve`. `state` and `whoami` always do. See [How the control plane works](/docs/serve). |
| `--limit N` | `runs --remote` | Print the newest `N` runs, from 1 to 200, 50 by default. |
| `--server URL` | `login`, `logout`, `plan`, `apply`, `approve`, `show`, `state`, `runs`, `whoami`, `repo`, `ci`, `ui`, `mcp` | Run on the control plane at `URL`, or on the dev control plane with `--server dev`. It implies `--remote` and comes before `WRIT_SERVER` and your session. |
| `--stack NAME` | `plan`, `apply`, `runs` with `--remote` | The stack's name on `writ serve`. For `plan` and `apply`, the default is its path from the Git work tree, or its directory's name outside one. `runs` lists only that stack's runs when it's given, and every stack's runs in the environment when it isn't. |
| `--hint-merge-request N` | `plan` with `--remote` | The merge request the plan belongs to, which `writ serve` keeps only for a merge request pipeline. |
| `--commit SHA`, `--repo NAME` | `plan` and `apply` with `--remote` | Plan this commit of the repository, and read no file. A CI job's token sets its repository and its commit, and `writ serve` refuses another. |

These global flags work before or after the command:

| Flag | Meaning |
| --- | --- |
| `--dir DIR` | The stack directory. The default is the current directory. |
| `--env ENV` | The environment of the control plane to run in. `WRIT_ENV` sets the same thing. |
| `--verbose` | Log at debug level, to stderr. |

## Output for people

Without `--json`, `writ plan --remote` and `writ apply --remote` print the plan and the apply as the control plane writes them, for a person reading a terminal or a CI log.

- **A plan lists each change of the masked plan,** one line per resource with its address and action (`+` create, `~` update, `-` delete, `-/+` replace with the paths that force it, `<-` import), then OpenTofu's summary line, the outputs that change, the policy decision, and any warnings.
- **An apply prints when its run ends:** each resource's outcome and the run's summary. `writ show --remote RUN` prints it again later.
- **Plain text.** The plan and apply text is printed as the control plane wrote it, without color, and a value in it never prints raw escape codes.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | The command succeeded. |
| 1 | The command failed: a diagnostic, a refused or failed plan or apply, a request that `writ serve` refused, or an error that stopped it. |
| 2 | The command line or the command's input is wrong: an unknown flag, a missing argument, a directory that isn't an OpenTofu stack, or no control plane to send it to. It doesn't mean nothing changed: `writ agent init` can write `AGENTS.md` before it exits 2. |

With `--json`, stdout has one JSON document on each of the three.

## Environment variables

| Variable | Meaning |
| --- | --- |
| `WRIT_ENV` | The environment to run in. The same as `--env`. |
| `WRIT_SERVER` | The control plane the remote commands use, after `--server`. |
| `WRIT_ID_TOKEN` | The CI job's OIDC token the remote commands send. It comes before a session from `writ login`. |
| `XDG_CONFIG_HOME` | Where `writ login` keeps its sessions, in `writ/sessions.json`. The default is `~/.config`. |
| `XDG_DATA_HOME` | Where `writ serve --dev` keeps its data, under `writ/dev`, and where the remote commands look for its `client.json`. The default is `~/.local/share`. |
| `WRIT_CACHE_DIR` | The directory for provider binaries and cached schemas, which `writ import bulk` fills and the `schema` tool of `writ mcp` reads. |
| `NO_COLOR` | A value that isn't empty turns off color on a terminal. See [Output for people](/docs/commands#output-for-people). |

`writ import bulk` and the `import_bulk` tool of `writ mcp` run providers with the environment `writ` runs in. A provider's own settings, such as `AWS_PROFILE`, work.
