Output contracts #

Five rules that hold for every command. Everything else about output, like which flags exist and what a command prints, is in atgc <command> --help or in the output itself.

stdout is the answer; stderr is everything else #

On every flag. Notes, warnings and progress go to stderr, so -q/-qq and ATGC_LOG can turn them down without touching the answer or the exit code.

--json is one value on stdout #

Every command that reads or writes something takes it. about, agent and completion do not: their output is already the whole answer and there is no second rendering to choose.

Reads emit the derived view rather than the raw record. State, number and resolved handle are computed from several sources and are not fields on anything. Writes emit what they did, always carrying dry_run; under --dry-run the identifiers a write would have minted are null rather than guessed.

pr checkout is in neither group. It writes no record, so it takes no --dry-run and carries no dry_run. What it did is local git: a branch, and under --worktree a directory. Those are what it prints.

Two more sit outside it. pr diff prints a patch, and a patch is the thing git am and git apply read: wrapping it in an object would mean every caller unwrapping it again, and --interdiff hands the whole job to git range-diff besides. auth login has non-interactive callers and still takes no --json, because the one value stdout may carry would have to be the authorization URL, which is printed long before the login has a result to report. Off a terminal it prints that URL alone on a line instead — no prose and no link escape, since whatever is reading is going to open it — and the login's own lines move to stderr. A CI job is the one session it refuses, because there is nothing there that could open the page. The other five auth verbs take the flag.

auth status --json says resolved, not active. The field marks the account that answered, at whichever of the five ranks answered — which is a different thing from the default, one rank down, that answers only when nothing else does. A row can be resolved without being the default and the other way round, and one word for both is how that got confused. The rename is a breaking change to the shape and has no alias: unlike the registry on disk, nothing reads an old --json document back.

api is the one read-or-write command with no --json. Its output is the service's own answer, which is already JSON, so there is nothing for the flag to switch between. What --json would buy is on by default there: one value on stdout, no colour, no padding. Under --dry-run that value is the request it would have sent, carrying dry_run like every other write.

The three logs readers are the one place that prints JSON Lines: one log record per line, as the bytes are on disk, and nothing else on stdout. They cannot be one value, because --follow is an unbounded stream that ends when somebody interrupts it — the closing ] of an array is a byte that never arrives, and a caller that read to EOF before parsing would hang on the case the flag is for. Emitting an array without --follow and lines with it would be worse: the same flag on the same command returning two shapes depending on another flag. So it is lines on every flag, and an empty result is zero lines rather than []. Everything else about --json still holds here: the unreadable-line warnings, the "no log yet" note and the --follow "waiting …" step are all on stderr.

Being the bytes on disk has one further consequence, and it is deliberate: the log record shape is the schema. ts, inv and seq, the snake_case event tag, and the fields of each event are a public interface under the stability rules below, and crate::logging::file's Record and the three Event enums say so where somebody renaming a field will see it. The alternative was to re-serialize each line through this build's own enum, which would silently drop any field a newer atgc had added — exactly during the incident where an old binary is reading a new machine's log.

Unknown is null, never "?". No @ on handles. No colour.

Stability: within a minor version, a field may be added in a feat. Removing or renaming one is a breaking !. See CONTRIBUTING.md's versioning rules.

A date column is UTC #

Every listing that shows a created or opened date shows the UTC calendar date of the instant, whatever offset the record was written with. Records carry a whole RFC 3339 timestamp and a column shows ten characters of it, so something has to choose between three dates: the writer's own offset, the reader's local zone, and UTC.

UTC is the only one that makes two rows comparable, which is what a column is for. The writer's offset means two rows of one listing can disagree by a day about the same instant, and the reader's zone means the same listing prints differently on two machines and a piped listing depends on TZ.

The visible consequence is intended: a record written at +03:00 just before midnight prints the previous day. A timestamp that does not parse falls back to its first ten characters rather than erroring — a malformed record must not stop a listing rendering — and an empty one prints empty rather than a placeholder. --json is unaffected: it emits the stamp as the record carries it, and the date column is a rendering.

Somebody else's text is not an instruction #

Every title, body, comment and excerpt a command prints came out of a record written by an account atgc has never met, and opening a pull or an issue against a repo needs no permission on it. A terminal does not draw a string, it interprets one, so anything printed at a person first goes through term::text: C0 control characters except \n and \t are dropped, and so are U+007F and the C1 range. A value going into a fixed-width column loses its \n and \t as well, because a title holding a newline prints a second line that reads as a second row.

Dropped rather than escaped. \x1b[2J prints as [2J: the reader sees that something was there and nothing acts on it.

Two outputs are exempt, both because they are not lines for a person. --json emits what the record holds — serde escapes control characters, and a caller reading the document back wants the value, not a rendering of it. pr diff emits a patch, which is bytes for git am; filtering one would corrupt it, and git's own pager decides what to do with what is in there.

Exit status says which kind of failure #

The numbers are a public interface. crate::exit::Exit spells them out as a match so that inserting a variant cannot renumber the rest.

atgc doctor local and atgc doctor remote are the two reports with an answer and a non-zero status. The report is the answer, so it goes on stdout, and the status summarises the report rather than standing in for it. Each failing row carries the status the operation it stands for would have exited with: a missing session is 3, a scope gap or an unregistered push key 4, a host that did not answer 6. With more than one, the first row wins. A warning never decides it, or doctor local would fail in every checkout that has never been near Tangled.

The two ask opposite questions, and only one of them can say what to do about the answer. doctor local orders its rows by what depends on what, so the first broken row is the one to fix first and it says so. doctor remote reports on services that need nothing from each other, so it names the row the status came from and stops there. That is why every remedy in a doctor remote report is null: no command here mends somebody else's host.

doctor remote --json adds one field beside the rows: lag_seconds, how far Bobbin's newest pull request of yours trails the newest in your PDS. It is the index row as a number, because the audience for that object is something that alerts, and a threshold cannot be read out of a sentence. It is null wherever the row is not a measurement, meaning no account selected, no pull records of your own, or either side declining to answer. It is negative where Bobbin is ahead, which is not lag: its listing spans every author and the comparison counts only yours.