JSON output
The contract for every --json document: formats, fields, and what may change.
Every writ command but writ serve, writ mcp, writ ci, and writ help takes --json and prints one JSON document on stdout. --help and -h print plain usage text and exit 0 even with --json. The sections below are the contract for each document. Logs go to stderr, so stdout is always exactly one document, on every exit code.
Rules for every document
formatgives the shape and its version, such aswrit.remote-plan/v0. Within a version, a field is only ever added, never removed or retyped. Ignore fields you don't know.okis true when the command succeeded. It matches the exit code:ok: trueexits 0, andok: falseexits 1, or 2 when the command couldn't start as given.- A document with
ok: falsesays why indiagnostics, or, for an apply, instatus. - Writ's own lists are always present. An empty list is
[], nevernullor missing. The masked plan document isn't one of these lists' documents: it's Writ's reduced form of OpenTofu's plan JSON. It keeps only the keys the mask lists, hasvariablesas the list of variable names, always haserrored,variables,configuration, andresource_changes, and a value or list in it can benull. - The mask replaces with
(sensitive)each secret it knows in every document of a plan, a run, the state index, and their diagnostics: a value OpenTofu marks sensitive, the value of a variable declaredsensitive = true, a valuewrit servegave the run, and the value of an attribute with a name that says it contains a secret. A secret it doesn't know reaches these documents in the clear. What the mask can't do lists those cases.
Exit codes, and one document always
| Exit code | Meaning | ok | The diagnostic's class |
|---|---|---|---|
| 0 | The command succeeded. | true | Warnings only, if any |
| 1 | The command failed: a diagnostic, a refused or failed plan or apply, a request that writ serve refused, a plan that writ apply --remote --yes can't apply because it needs approvals, or an error that stopped it before it could do its work. | false | Any class |
| 2 | The command couldn't start as given: an unknown command or flag, a missing argument, a value that doesn't parse, 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. | false | usage |
With --json, stdout has exactly one document on all three. A command that stops before it can do its work prints an empty document with ok: false and one diagnostic: its own format for writ plan, writ apply, writ state adopt, writ runs, writ import, writ agent init, writ login, and writ logout, and writ.error/v0 for writ whoami, writ show, writ approve, writ repo, and writ ui. Here's writ plan --json with no --remote, which exits 2:
{"format":"writ.remote-plan/v0","ok":false,"plan":null,"document":null,"text":"","policy":null,"diagnostics":[{"severity":"error","class":"usage","message":"plan runs on the control plane: writ plan --remote"}]}Output of a real run, 2026-11-16.
Two classes exist for these documents:
-
usage: the input was wrong, and the caller can fix it. When the command line was wrong, or the command couldn't start, the command exits 2 and stderr saysrun writ help for usage; some documents also carry that advice in the diagnostic'sfix, and the documents ofplan,apply, andrunsdon't. Ausagediagnostic in a document that the command printed after it started exits 1: a request thatwrit serverefused, such as one that names an environment that isn't a name, an OpenTofu step that failed in a plan or an apply, an apply that ran pastlimits.apply_timeout, or anAGENTS.mdwith markers thatwrit agent initcan't read. Ausagewarning, such as a file thatwrit agent initkept, fails nothing. -
internal: the command couldn't run for a reason that isn't a finding about the stack: a file it couldn't read or write, or a bug in writ. The message is the error. A bug also prints a stack trace on stderr. -
--jsonis read from the raw command line, so a command line that doesn't parse is answered in JSON too. A command line with no command that writ knows prints{"format":"writ.error/v0","ok":false,"diagnostics":[...]}. -
The same message also goes to stderr as
writ: <message>. -
--helpprints usage text, not JSON.
Diagnostic
Every document that can fail carries diagnostics, a list of:
{"severity":"error","class":"usage","message":". is not an OpenTofu stack: writ import bulk needs .tf files, a .terraform.lock.hcl, and no .writ file; run tofu init first","fix":{"message":"run writ help for usage","safe":false,"edits":[]}}Output of a real run, 2026-11-16: the diagnostics of writ import bulk SELECTION.json --json in a directory with no lock file.
severityiserrororwarning. Only errors fail a command.classis one ofsyntax,provider,state,state-io,saved-plan,usage,internal,auth,denied, andpolicy.syntaxmeans the config ofwrit servedoesn't parse.providermeans a provider failed, such as whenwrit import bulkreads an object, or a stack's lock file or a Git host's answer couldn't be read.statemeans the plan no longer fits the state: plan again.state-iomeans the control database was busy, unreachable, or failed: the plan is still good, and the same command may pass later.saved-planmeans the control plane refused a saved plan: make the plan again.usagemeans the caller's input was wrong, andinternalthat the command couldn't run for another reason; see exit codes.authanddeniedcome fromwrit serve:authmeans the request had no token or its token failed a check,deniedmeans no grant allows it, andpolicymeans a policy refused the apply. Errors lists the common messages of each class and what to do.file,line,col,end_line, andend_colare omitted when the diagnostic has no source location, as for every diagnostic ofwrit serve.fileis a path relative to the stack directory.fixis omitted when writ knows no fix. A fix is advice:fix.messagesays what to do, such asrun writ help for usage.fix.safeis alwaysfalse, andfix.editsis always[]. Both stay in the document for compatibility, so a reader that expects them still parses it.- The documents of
writ serve, and the commands that print one, carry diagnostics withseverity,class, andmessageonly.
A plan or run that a build from before the first release kept can carry a class that no longer exists, such as type or goal.
writ import bulk --json (writ.import-bulk/v0)
writ import bulk reads many objects into an OpenTofu stack, writes one new .tf file that declares them and one that records them, writes no state, and plans nothing. Import many objects has the details.
fileis the new.tffile,""when none was written, andimports_filethe file beside it that records each object forwrit import accept --imports.importedis false andrunis"", because no state is written, andplanisnull.objectslists each object in the order the file declares it:addr, the OpenTofu address,type, OpenTofu's type name,id, the import id, andorigin, the entry of the selection that picked it, such asobjects[1].values[0]. When the import id is one of the object's own secrets,idis""andsecret_idis true.groupscounts thefor_eachgroups, andsinglesthe blocks of one object.linkedcounts the literals written as references, andliteralsthe typed reference slots that kept a literal.paramslists each variable the code declares for a sensitive value. The value is never printed.problemslists each object that wasn't imported or was skipped, and each field that needs attention:kindisnot imported,skipped, orimported, needs attention, withfrom, the entry or address, andreason. An objectnot importedfails the run, and nothing is written.
writ import accept --imports FILE PLAN --json (writ.import-accept/v0)
{"format":"writ.import-accept/v0","ok":true,"objects":1,"imports":1,"refusals":[],"settings":[{"address":"nomad_job.nomad_job_import_web_default","attribute":"deregister_on_destroy","value":true,"provider":"registry.opentofu.org/hashicorp/nomad","version":"2.6.1"},{"address":"nomad_job.nomad_job_import_web_default","attribute":"deregister_on_id_change","value":true,"provider":"registry.opentofu.org/hashicorp/nomad","version":"2.6.1"},{"address":"nomad_job.nomad_job_import_web_default","attribute":"detach","value":true,"provider":"registry.opentofu.org/hashicorp/nomad","version":"2.6.1"},{"address":"nomad_job.nomad_job_import_web_default","attribute":"preserve_counts","value":false,"provider":"registry.opentofu.org/hashicorp/nomad","version":"2.6.1"},{"address":"nomad_job.nomad_job_import_web_default","attribute":"read_allocation_ids","value":false,"provider":"registry.opentofu.org/hashicorp/nomad","version":"2.6.1"},{"address":"nomad_job.nomad_job_import_web_default","attribute":"rerun_if_dead","value":false,"provider":"registry.opentofu.org/hashicorp/nomad","version":"2.6.1"}],"diagnostics":[]}objectscounts the objects that--importsrecords, andimportsthose that the plan imports at their address and by their import id, as a no-op or as an update of provider-only settings alone.refusalslists each reason the plan isn't accepted:addressis the resource change,""for the plan as a whole, andreasonsays what it plans.okis true when there's none. An import update of a plan given as JSON, not as the plan file thattofu plan -outsaved, is always refused, and itsreasonsays to pass the saved plan file. Areasoncontains no secret of the plan: an attribute name that contains one shows(sensitive)in its place.settingslists each provider-only setting that an accepted plan sets in place on an object it imports, from the named list in import-bulk.md:addressis the resource change,attributethe setting,valuethe value the plan sets, andproviderandversionthe provider it was measured on. It's empty when the plan isn't accepted.
writ import has two forms, and each has its own document. A command line that fails before the command reports prints writ.import-bulk/v0 when its first argument that isn't a flag is bulk and the next is a .json file, -, or nothing, writ.import-accept/v0 when it's accept and one more argument follows, and writ.error/v0 otherwise.
The schema tool of writ mcp (writ.provider-schema/v0)
The schema tool reads the cached schemas of the providers that a stack's .terraform.lock.hcl pins.
providerslists each provider of the lock file with itssourceandversion.typeslists each type asked for:type, the resource type ordata.NAMEfor a data source,kind,provider, andschema, the type's attributes and blocks as the provider describes them.listshas, for each provider asked for by name, itsresourcesanddata_sources.diagnosticscarryseverity,class, andmessage.
writ runs --remote --json (writ.remote-runs/v0)
writ runs --remote --json prints the writ.remote-runs/v0 document of GET /v1/applies, which the API describes.
writ agent init --json (writ.agent-init/v0)
{"format":"writ.agent-init/v0","ok":true,"files":[{"path":"AGENTS.md","action":"appended"},{"path":".agents/skills/writ/SKILL.md","action":"created"},{"path":".agents/skills/writ/reference.md","action":"kept"},{"path":".claude/skills/writ/SKILL.md","action":"created"},{"path":".claude/skills/writ/reference.md","action":"created"}],"diagnostics":[{"severity":"warning","class":"usage","message":"kept .agents/skills/writ/reference.md: it differs from what this writ writes","fix":{"message":"pass --force to replace it with this writ's","safe":false,"edits":[]}}]}fileslists each pathwrit agent initwrites or removes, from the repository root, in this order.actioniscreated(the file wasn't there),appended(AGENTS.mdhad no Writ section and got one at its end),updated(Writ's section was rewritten, or with--forcea skill file),unchanged,kept(the file differs and was left alone), orremoved(an olderwrit agent initwrote it:.agents/skills/writ/spec.md, or the symbolic link at.claude/skills/writ, or with--forcea symbolic link of the user's at a skill directory or a skill file, which is replaced). Eachkeptfile has ausagewarning.- An
AGENTS.mdwith broken markers, a marker without its pair or two sections, is ausageerror. Nothing is written,filesis[], andokis false.
writ version --json (writ.version/v0)
{"format": "writ.version/v0", "ok": true, "version": "v0.1.0"}Documents of writ serve
The API answers with these documents. A remote plan's document is the masked plan document: OpenTofu's plan JSON after the mask, with only the keys the mask lists, which Policy describes. A plan that ended without one has {"format":"writ.plan.json/v2","ok":false,"diagnostics":[...]} there instead. A run's document is writ.tofu-apply/v0, which How an OpenTofu plan is approved and applied describes, or {"format":"writ.apply/v0","ok":false,"applied":false,"status":"apply-failed","diagnostics":[...]} for an apply that couldn't start or that writ serve lost, as when it stopped during the run.
| Format | Route | Printed by |
|---|---|---|
writ.server/v0 | GET /v1/server | |
writ.health/v0 | GET /healthz | |
writ.whoami/v0 | GET /v1/whoami | writ whoami --json |
writ.device/v0 | POST /v1/auth/device | |
writ.browser/v0 | POST /v1/auth/browser | |
writ.session/v0 | POST /v1/auth/device/token, POST /v1/auth/browser/token, DELETE /v1/auth/session | |
writ.sessions/v0 | GET /v1/sessions, DELETE /v1/sessions/{id} | |
writ.login/v0 | writ login --json | |
writ.logout/v0 | writ logout --json | |
writ.plan-request/v1 | the body of POST /v1/plans | |
writ.remote-plan/v0 | POST /v1/plans, GET /v1/plans/{id} | writ plan --remote --json, writ show --remote --json |
writ.remote-plans/v0 | GET /v1/plans | |
writ.approve-request/v0 | the body of POST /v1/approvals, and optionally of POST /v1/plans/{id}/approvals | |
writ.approve/v0 | POST /v1/plans/{id}/approvals, POST /v1/approvals, DELETE /v1/plans/{id}/approvals/mine | writ approve --remote --json |
writ.run-request/v1 | the body of POST /v1/runs | |
writ.remote-run/v0 | POST /v1/runs, GET /v1/runs/{id} | writ apply --remote --json, writ show --remote RUN --json |
writ.remote-runs/v0 | GET /v1/applies | writ runs --remote --json |
writ.apply-outcome/v0 | POST /v1/apply-requests/{key}/outcome | writ show --remote --request KEY --json, and writ apply --remote --json when no run started or the route didn't answer |
writ.config/v0 | GET /v1/config | |
writ.policy/v0 | GET /v1/policy | the policy tool of writ mcp |
writ.repo-request/v0 | the body of POST /v1/repos | |
writ.repo/v0 | POST /v1/repos, GET /v1/repos/{name} | writ repo add --json, writ repo show --json |
writ.repos/v0 | GET /v1/repos | writ repo list --json |
writ.ui-link/v0 | POST /v1/dev/ui-link | writ ui --json |
writ.drift/v0 | GET /v1/drift | |
writ.state-index/v0 | GET /v1/index | |
writ.overview/v0 | GET /v1/overview | |
writ.state-adopt-request/v0 | the body of POST /v1/state/adopt | |
writ.state-adopt/v0 | POST /v1/state/adopt | writ state adopt --json |
writ.error/v0 | a route that doesn't exist |
A refused request answers with its route's format, ok: false, and one diagnostic of class auth, denied, usage, state, saved-plan, state-io, provider, or internal. If writ serve can't write a request's audit row, it returns 503 with one state-io diagnostic, whatever it would have returned. An apply that a policy refuses answers 403 with a diagnostic of class policy that names the plan, and one of class policy for each result of the decision: an error for a result that denies, and a warning for one that warns, each OUTCOME: [SET] MESSAGE.
writ.server/v0hasversion,url,dev,issuers(name,kind,url,identity),login, anddevice_issuers.devistrueforwrit serve --dev, which is how a CLI finds the dev control plane, andfalsefor every other.loginistruewhen a people issuer exists, sowrit loginis set up.device_issuerslists the people issuers that offer the device flow, whichwrit loginuses with them by default. It signs in with the others in a browser. Awrit servefrom before browser sign-in sends nodevice_issuers, andwrit loginuses the device flow with it.writ.whoami/v0hasprincipal(kind:ci-job,person, ordev,issuer,subject,display,person(IDENTITY/user/ID, ordev/USERunderwrit serve --dev),expires_at, andsession, the id of a person's session, absent for other kinds),teams, andgrants.writ.device/v0hasissuer,user_code,verification_uri,verification_uri_completewhen the identity provider gave one,handle,interval_seconds, andexpires_at. The handle refers to the sign-in inPOST /v1/auth/device/tokenand works once.writ.browser/v0hasissuer,auth_url, the identity provider's sign-in page for this sign-in,handle, andexpires_at. The handle refers to the sign-in inPOST /v1/auth/browser/tokenand works once.writ.session/v0hasstatus:pendingwithinterval_seconds,signed-in, orended, andsessiononce signed in or ended.tokenis set in one answer only: the poll, or thePOST /v1/auth/browser/token, that signs the person in.writ.sessions/v0hassessions, each withid,carrier(cliorbrowser),person,display,issuer,subject,teams,created_at,ends_at, andlast_seen_at, to the minute. It never contains a token.writ.login/v0hasserverandsession, as inwrit.session/v0, without the token. The prompts ofwrit login --jsongo to stderr.writ.logout/v0hasserver,session(the id), andended,falsewhen the session had already ended on the server.writ.config/v0hasurl,issuers(name,kind,url,identity),teams(name,issuer,matchasclaimandvalues),grants(grant, numbered from 1,teams,stacks,envs,can,risks),envs(name),forges(name,kind,url),poll_every,plan_ttl, andsession_ttlas Go durations,ui, andadmin.adminhaslimitsandretentionfor a principal withadmin, and isnullfor every other. The document contains no file path, no database URL, and no secret. Underwrit serve --dev,envslists each environment that has a plan or a state.writ.policy/v0hassets, in config order, each withname,level(mandatoryoradvisory), andfiles, by name, each withname, relative to the set's directory, andtext, the.regofile. It contains no path. Thepolicytool ofwrit mcpreturns it with only the set itssetnames, and withfileonly that file of it.writ.plan-request/v1hasenv,stackswith one stack,hints, andsource.sourcehasrepo,ref, andcommit, the commit's full id. A CI job may send{}, and its token's project andshafill it. A request with any other field, such as the retiredallow,target,exclude,replace,params, orbundle, is refused. The plan ofwrit.remote-plan/v0hassource:{"kind": "commit", "repo", "ref", "commit", "ref_check"}.ref_checkison-refwhen the forge showed the commit is the ref's commit or an ancestor of it, andno-refwhen the plan names no ref. A plan is refused when its ref doesn't contain its commit.- The plan of
writ.remote-plan/v0hasstatus:planning,pending,approved,applying,applied,refused,failed,expired, orsuperseded, withsuperseded_whyfor the last.approvalshasneed,rules(the 1-based positions of the approval rules that matched),approved_by(eachperson,display,via, andat), andteams_that_may_approve.runrefers to the run that applied the plan.GET /v1/plans/{id}addshistory, each change of status withat,from,to,personandbywhen a person made it,run, andreason. See Track a plan's status. writ.remote-plan/v0haspolicy, the plan point'swrit.policy-decision/v1of a plan of an OpenTofu stack that a policy evaluated, andnullfor any other plan.writ.remote-run/v0haspolicy, the apply point's decision that let the run begin, ornull. A decision hasformat,point(planorapply),outcome(pass,warn, ordeny),at,input, the hex SHA-256 of the policy's input, at the apply pointapprovals, the hex SHA-256 of the ids and approvers of the approvals it judged, andresults, each withset,level(mandatoryoradvisory),rule(the Rego rule, such asdeny_rsa, orerrorwhen the set failed),outcome(denyorwarn, what the result does), andmessage, swept by the mask and then cut at 1,000 bytes, or before a(sensitive)marker that the cut falls inside. A plan with the decisiondenyisrefused.writ.approve-request/v0haspipeline, true to approve every live plan of the CI job's own pipeline.writ.approve/v0hasplans, each withid,env,stack,status,need, andapproved_by, as the plans are after the request.writ.run-request/v1hasplan, a plan's id, with an optionaloverridereason, orenv,stackswith one stack, andmerged,{"repo", "commit"}, which a CI job may send as{}.writ.remote-run/v0hasrun,document, the run's document once the run ends andnullbefore, andtext, the apply aswrit apply --remoteprints it.runhasid,plan,status(applying,applied, orfailed),env,stack,actor,approved_by,override,named_by(planormerged),merged_commit,role_session,started_at, andended_at. A 503 ofPOST /v1/runsaddsoutcome:nonewhen the request started no run, andunknownwhenwrit servecan't tell. WhenPOST /v1/runsis refused because its key is closed with no run, the refusal addskey_closed: true: a 409, or a 503 withoutcomenone. No request with that key starts a run, so a client sends a new key.writ.apply-outcome/v0haskey,outcome(startedornone, andunknownin a 503 or whenwrit apply --remotegot no answer), andrun, as inwrit.remote-run/v0forstarted, elsenull.writ.repo/v0hasrepo,commit,stacks, anddiagnostics.repohasname,forge,kind(gitlabordir),forge_url,project,project_id,path,prefix,default_branch,web_url,origin(apiorconfig),added_by,added_at,head,head_read_at,polled_at, anderror, why the last poll failed or"".commitis the head read, withsha,read_at,files, andbytes, ornull. Each ofstacksis an OpenTofu stack, a directory with a committed.terraform.lock.hcland.tfor.tofufiles, withstack, its name on the control plane,dir, its directory in the project,servedandnot_served, the environments this control plane plans it in and the ones it doesn't, andproviders(source,version, andruns, whether this control plane runs that provider).diagnosticsare discovery's.writ.repos/v0haspinned, set when the config lists the repositories, andrepos, each therepoofwrit.repo/v0withstacks, the count found at its head.writ.ui-link/v0hasurl, a control UI sign-in link with a code that works once, andexpires_at.writ.drift/v0hasstacks, byenvand thenstack, andmore, true when the limit left readable stacks out. Each stack hasstack,env,backend(httpors3),resources(the rows of its state index),indexed_version(the state version or S3 serial the index was read from, 0 when nothing indexed it),indexed_at,outside_write(serialandseen_atof the newest serial on S3 that no apply ofwrit servewrote, ornull),checking(true while a drift check plans it), andcheck, the newest drift check that ended, ornull.checkhasplan(the id of its plan, never approved or applied,""when it made none),status(clean,drifted, orfailed),started_at,checked_at,repoandcommit(what it planned),outside(resources OpenTofu found changed outside it) andcode(changes an apply of the code would make),drifted_since(when the first of an unbroken run of drifted checks ended,""when not drifted),changes, anderror(why a failed check made no plan, ordrift unknown: no secret set for state version N of stack@envfor a check of a state with no secret set, which keeps nothing else). Each ofchanges, at most 200, hasaddress,kind(outsideorcode),action(create,update,delete,replace,forget, orimport), andattributes, the names of the top-level attributes that change, left out when none. It holds no value.writ.state-index/v0hasstack,env,backend,indexed_version,lineage(of a state on S3,""on the http backend),indexed_at,outside_writeas inwrit.drift/v0, andresources, by address, each withaddress,type,provider, and the attributes of the state index's allow-list:id,arn,identifier,region,namespace, andmodify_index,""for one the state doesn't hold as a string, marks sensitive, or the mask swept.writ.overview/v0hasenvs, each environment where the principal may read a stack, withname,plans(the count of its plans in each live status:planning,pending,approved, andapplying, each asGET /v1/plans/{id}shows it, from at most 200 plans of each status that the principal may read),plans_more(true when the principal may read more, so the counts are floors and a plan about to expire may be missing fromalerts),alerts_more(true whenalertsleaves out drift alerts or failed runs of the environment),failed(runs that failed in the last 24 hours),stacks(stacks whose statewrit servekeeps or reads),checked(those with a drift check that ended),drifted(those whose last check found drift), andcheck_failed(those whose last check failed). The counts offailedand of stacks take in every run and stack the principal may read. Every count, list, and flag leaves out what the principal may not read before it counts or cuts, so a stack, plan, or run the principal may not read changes nothing in the answer.stacks, byenvand thenstack, are the first 200 whose statewrit servekeeps or reads, withstacks_morewhen more have state, and the stacks a live plan names that have no state yet, each withenv,stack,plansas inenvs, anddrift, its row ofwrit.drift/v0, ornullfor a stack with no state yet. A stack with state past the first 200 is left out, never listed withdriftnull; its environment'sstackscount holds it.applying,pending, andplanningare the plans of that status asGET /v1/plans/{id}shows it, newest first, each{"plan", "run"}:planas inwrit.remote-plans/v0, andrun, its run as inwrit.remote-runs/v0, ornullbefore one began.alertseach havekind(drifted,drift-check-failed,outside-write,run-failed,plan-expiring, orrepo-poll-failed),env,stack,plan,run, andrepo,""where the kind names none,message, what happened in words, andat: the drift alerts of at most 200 stacks of each environment, bystack, then each environment's newest 200 failed runs, newest first, then pending and approved plans that expire within 2 hours or a quarter ofplan_ttl, whichever is shorter, then failed polls. Each environment'salerts_moreis true when the limits left its drift alerts or failed runs out.reposhascount,polled_at, the newest poll, andfailed, each repository whose last poll failed withname,error, anderror_at, or isnullfor a principal that may read nothing.writ.state-adopt-request/v0hasenv,stack,reason(10 to 500 characters), and one ofversion, a state version of a stack on the http backend, andserial, a serial of a stack's state on S3. The other is0or absent.writ.state-adopt/v0hasstack,env,backend(httpors3),version(the state version on the http backend,0on S3),serialandlineage(of the state),repoandcommit(the code whose providers read the state),resources(the rows of the state index the adoption read),indexed(truewhen the index took them), and onewarningdiagnostic of classstatethat names what the secret set can't hold.
This page is built from docs/json-output.md in the repository. It is also served as plain Markdown.