Writ

Commands

Every command and flag, exit codes, and environment variables.

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.

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

Commands

CommandWhat it does
writ import accept --imports FILE PLANAccept 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.
writ import bulk SELECTION.jsonTake 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.
writ agent initWrite 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.
writ mcpServe 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.
writ versionPrint the version.
writ serve --config FILERun the control plane. --check prints what each team can do and serves nothing. See Run a control plane.
writ serve --devRun 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.
writ plan --remotePlan an OpenTofu stack on the control plane, wait, and print the plan the server keeps. In a clean work tree of a repository 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 gives the server and token it uses. Needs --env, except on the dev control plane.
writ plan --remote --stack NAME --commit SHAPlan 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/PROJECTAdd 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.
writ repo add [NAME] DIRUnder writ serve --dev, add the local Git repository that contains DIR, such as ..
writ repo list, writ repo show NAMEPrint 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 NAMEPrint 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 uiPrint the control UI's address. Under writ serve --dev, print a sign-in link that works once, for 10 minutes.
writ show --remote IDPrint a plan writ serve keeps, by its id or its ref, or a run, by its id.
writ show --remote --request KEYPrint 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 IDApprove a plan another person created. --withdraw takes the approval back until the plan starts applying. See Approve and apply a plan.
writ approve --remote --pipelineIn a CI job, approve every live plan of the job's own pipeline, all or none.
writ apply --remote IDApply 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.
writ apply --remote --merged --env ENV --stack NAMEAfter 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 --yesPlan as writ plan --remote does, and apply the plan when no approval rule needs one.
writ runs --remotePrint 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 S3Seal 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.
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.
writ logout [URL]End your session on the control plane and delete it from the session file.
writ whoamiPrint 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

FlagCommandsMeaning
--jsonevery command but serve, mcp, ci, and helpPrint one JSON document on stdout. With --help or -h, the usage text prints instead. See JSON output.
--out FILEimport bulkThe new file to write in the stack, imported.tf by default.
--imports FILEimport accept PLANThe 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 IDimport bulkSelect objects without a selection file: the type, and an import id to read. Repeat --id for each object.
--provider ADDRimport bulkRead the objects through the provider configuration at ADDR.
--max-objects N, --max-bytes Nimport bulkRefuse to read more than N objects, 500 by default, or to write a file larger than N bytes, 1 MiB by default.
--yesapply --remotePlan as writ plan --remote does, and apply the plan when no approval rule needs one.
--remoteplan, apply, approve, show, runs, state, whoamiRun against writ serve. state and whoami always do. See How the control plane works.
--limit Nruns --remotePrint the newest N runs, from 1 to 200, 50 by default.
--server URLlogin, logout, plan, apply, approve, show, state, runs, whoami, repo, ci, ui, mcpRun 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 NAMEplan, apply, runs with --remoteThe 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 Nplan with --remoteThe merge request the plan belongs to, which writ serve keeps only for a merge request pipeline.
--commit SHA, --repo NAMEplan and apply with --remotePlan 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:

FlagMeaning
--dir DIRThe stack directory. The default is the current directory.
--env ENVThe environment of the control plane to run in. WRIT_ENV sets the same thing.
--verboseLog 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

CodeMeaning
0The command succeeded.
1The command failed: a diagnostic, a refused or failed plan or apply, a request that writ serve refused, or an error that stopped it.
2The 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

VariableMeaning
WRIT_ENVThe environment to run in. The same as --env.
WRIT_SERVERThe control plane the remote commands use, after --server.
WRIT_ID_TOKENThe CI job's OIDC token the remote commands send. It comes before a session from writ login.
XDG_CONFIG_HOMEWhere writ login keeps its sessions, in writ/sessions.json. The default is ~/.config.
XDG_DATA_HOMEWhere 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_DIRThe directory for provider binaries and cached schemas, which writ import bulk fills and the schema tool of writ mcp reads.
NO_COLORA value that isn't empty turns off color on a terminal. See 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.

This page is built from docs/commands.md in the repository. It is also served as plain Markdown.

On this page