Scripting
The steps of the loop that a script or a shell prompt wants also run as
commands, without the interface: status, reviews, repositories,
summary, issues, issue, branch, pr, finish, announce, comment,
transition, assign and worklog, beside doctor, config, slack login and
db-clean. This page is what a script
can rely on from them — the exit status, which stream carries what, the JSON shapes, and the
flags that make a write safe to run unattended. Every command and flag is
listed in the command reference.
workflow status --json # where the work stands, as data
workflow reviews --json # what waits on your review, oldest first
workflow repositories --json | jq -r '.worktrees[].dir' # this repository's worktrees
workflow issues --view Sprint # a view's issues, one a line
workflow issue PROJ-7 --json # one issue in full, as data
cd "$(workflow branch PROJ-7 --fetch --worktree --yes | tail -n 1)" # start fresh, beside this checkout
workflow pr -n # what pr would push and open
workflow pr --yes # push, open, link and move, without asking
workflow pr --yes --json | jq .pull.url # the same, and the address it opened
workflow pr -y --draft --reviewer ana # open a draft, asking ana rather than the code owners
workflow pr --yes --announce # open it, then announce it once CI passes
workflow finish --dry-run # the three git commands that finish a merged branch
workflow announce --yes # announce it, unattended
workflow announce -y --channel '#release' # the same, in #release rather than messaging.channel
workflow announce --when-green --yes # announce it once CI passes, waiting in the foreground
workflow summary --json | jq -r .text # what you did on the previous working day
workflow summary --post --yes # post it to your team, unattended
git log -1 --format=%B | workflow comment PROJ-7 --yes # the text on stdin, never quoted
workflow transition PROJ-7 "In Review" --yes # move it, unattended
workflow assign PROJ-7 bo --yes # hand it to bo
workflow worklog PROJ-7 2h --comment "pairing" --yes # log the time spent on it
workflow --request-log requests.log doctor --online # a bug report's evidence
workflow -q branch PROJ-7 --yes # only warnings and errors on stderr
workflow --log-format json reviews 2>log.jsonl # what it says, as JSON, a line an entryExit status
A script tells one kind of failure from another by the exit status, never by the message, which is prose and may change.
| Status | Meaning | For example |
|---|---|---|
| 0 | Success. | |
| 1 | Any other failure. | Standard output that could not be written — a pipe whose reader has gone, a full disk — whatever else the command found; an issue that is not in the tracker, a pr --template the repository has no template of, named with the templates it has, a pr --base no branch has, a push that was rejected, a branch --fetch whose fetch failed, a finish whose git step failed, git missing, a repository whose branch cannot be read; a db-clean that finds a symlink or a directory where a database file belongs. |
| 2 | Usage: the command was called wrongly. | An unknown flag, command or subcommand; a wrong number of arguments; a summary --from or --to that is not a date written YYYY-MM-DD, or a period that runs backwards or is longer than a year and a day; summary --json --post, or --yes or --channel without --post; an announce or summary --channel where messaging posts through a webhook; status --plain with --json, which prints no status line for it to draw (ui.ascii draws a JSON run’s live line in ASCII); a pr --base git would refuse as a branch’s name, or pr --body with --template, or --announce with --draft; reviews --sort with an order it does not know; an issues --view naming no view jira.views configures; --port without --web, or outside 1 to 65535; --quiet with --verbose; a --log-format other than text, json or logfmt; --log, which is --request-log now; a confirmation, or the guided config init, with no terminal to answer it; a slack login answer left blank; a comment with nothing but white space on standard input; a transition whose status is blank; an assign whose username is blank; a worklog with a blank duration, or on a forge issue, which keeps no worklog. |
| 3 | Configuration: fix the file, a credential or a login. | No .workflow.json for doctor, config show or slack login; a file that does not parse; a required field left empty, or set unusably; a file other users can read; a ui.keys map the interface refuses to start on; no messaging configured for announce or summary --post; a worklog with no Jira configured, where the forge’s issues are the tracker; a slack login where Slack posts through a webhook, or messaging.kind names another service, or a repository’s own file names another app’s messaging.client_id, or whose credentials Slack refuses to refresh; no repository remote for reviews to find the forge from, or one on a host other than github.com, a ghe.com tenant, gitlab.com or the forge.host a forge.kind of github or gitlab describes; a credential that is missing — a Jira token, or a forge token from the file, the environment or gh auth login — or one a service rejected, a Jira 403 that says what the token may not do among them. |
| 4 | A refused precondition: the command would not go ahead because of what it found. | A pull request already open, or merging; no commits to open one for; no pull request to announce, or one merging; a check that failed on the pull request announce would announce; announce --when-green on a pull request that has merged, that reports no check within ten minutes, whose CI runs unchanged for two hours, or that starts merging or merges first, or is replaced while it waits, or that it heard nothing of for ten minutes — reads of CI that failed, a forge that did not list a pull request just opened, posts asked to wait — when what failed last has no status of its own (a credential refused exits 3, a service it could not reach or that asked it to wait 5); a finish on a branch that has not merged, has no base to return to, holds commits that neither merged nor are on its upstream, has commits made after the commit that merged — pushed or not, the newest five the base lacks named and the rest counted — or merged at a commit this clone lacks and could not fetch, or is not a branch of its own — read again once the finish is confirmed, so a commit made while it asked is refused too — or one whose checkout or base changed while it asked; a branch or configuration file that already exists; a directory that is not a git repository; a db-clean that could not remove a database file, as one another program holds open can be on Windows; a summary --post too long for the messaging service; a transition to a status the tracker does not offer from where the issue stands, which names those it does, or one whose move asks for fields, which names them. |
| 5 | Unreachable: a service did not answer, or asked you to wait. | Jira, the forge or the messaging service could not be reached — Slack among them when slack login refreshes — began an answer it did not finish in time, or answered with a redirect — a sign-in gateway in front of it, say — which is refused so the credential goes nowhere else; rate limiting. |
| 130 | Interrupted by Ctrl+C. |
cobra’s own help command is the one exception to 2: asked about a command
it does not know, it prints the root’s help and exits 0.
A command that reports several problems at once — doctor checks every
section, status DIR… every directory — exits with the first family any of
them belongs to, in the order 2, 3, 4, 5, 1. So doctor with no configuration
and no git exits 3: the configuration is what to fix first.
A .workflow.json that exists but does not parse stops every command with 3,
rather than being replaced by the defaults; one that cannot be opened stops
it with 1. With no file at all, the commands that can run on the defaults
still do.
With forge.cli set, the forge is asked through gh or glab, and a CLI
that is not signed in reads as a forge that could not be reached: 5, not 3.
workflow doctor --online says which it is.
The same families on the web
workflow --web answers a failed request with a problem code (see
Web API errors). The families line up:
| Exit status | Web problem code |
|---|---|
| 2 usage | bad_request (400); method_not_allowed (405), for a method the path does not answer; precondition_required (428), for a configuration save that names no revision to write over (no If-Match) |
| 3 configuration | not_set_up (422), for a service with nothing set up to ask: a Jira token not configured, a forge token not found, a base remote that names no forge or one workflow cannot tell, no Taskwarrior installed or never run, no git user.email; unprocessable (422), for a missing messaging service, an invalid configuration body or ui.keys map, a configuration file on disk that no longer reads as valid, a Jira token not accepted, or refused with a 403 that says what it may not do, a jira.base_url that is not a usable address, a forge token not accepted, and a forge.kind set without its forge.host |
| 4 refused precondition | conflict (409), a local database file that could not be removed among them; ci_failed (409), for an announcement a check failed on, as announce refuses one; announced_unconfirmed (409), for an announcement whose post began and was never confirmed, which announce instead asks about posting again; too_long (422), for a Summary longer than the messaging service takes in one message, as summary --post refuses one |
| 5 unreachable | unreachable (502), for a service that could not be reached or answered with a redirect; rate_limited (503), for one that asked to wait, with Retry-After when it said how long |
| 1 failure | internal (500); not_claimed (503), for an announcement the store could not claim, so nothing was posted; the web also answers not_found (404) for a missing issue or pull request template, unprocessable (422) for any other change Jira refused, a jira.base_url with no Jira API behind it, a forge address with no forge API behind it, or a request the forge refused for the token’s permissions, or a clean of the local data that found something other than the store’s own files, unreachable (502) for a status the forge does not document or a post the messaging service failed while taking, which may have gone out, and fetch_failed (502) for a fetch of the base remote that failed before starting work, as branch --fetch can — all of which the command line counts as a plain failure |
| none | check_failed (422), for a first configuration’s Jira check that did not pass, which config init instead asks about, offering to save the token anyway; unauthorized (401), for a request that presented no session of this run, which the command line never makes |
A missing Jira or forge credential answers not_set_up, saying how to set it
up, and a rejected one unprocessable, pointing at workflow doctor; the
command line exits 3 for both — except a Jira 403 that says what the
token may not do, which says Jira refused the request: doctor checks who a
token is, not what it may do.
The reads a script can make of the web’s API are listed under Scripting the API.
Standard output and standard error
Standard output carries the artifact — what a script would capture: the
JSON, the preview of what a write will do, the draft, the rows, and what a
write created. Standard error carries everything said about it: dry-run
lines, declined and done notices, warnings, guidance, the questions a command
asks, and the error itself, said once, after its tag: ERROR …. How standard
error is said — which of it, and in which format — is its own
section.
While a slow command waits on a service — doctor --online on each
credential, summary on each source, status DIR… on each directory, and
announce --when-green, or pr --announce, on the pull request’s CI — it
keeps a live line at the foot of standard error: a turning mark, what it is
doing (Checking Jira, Reading GitHub, Reading DIR, CI on #42), and a
bar of how many of how many are done (5 of 7). ui.ascii, or --plain on
status, draws the line in ASCII: a mark that turns through |, /, -
and \, and a bar of = and -. ui.motion: reduce holds the mark still,
on ◐, or * in ASCII. Whatever the command says meanwhile prints above the
line and stays; the line itself is erased when the wait ends. It is kept
only when standard error is a terminal, so a pipe, a redirect or a log never
holds it, nor any escape of its. With standard output on the same terminal,
what doctor --online reports while it waits prints above the line too, on
standard error, rather than under it; piped or redirected, standard output
gets the report as always.
| Command | stdout | stderr |
|---|---|---|
status | the line, or one row per directory, or the JSON | each service that refused to answer — Jira could not be read: …, GitHub could not be read: … — then each that is not set up, with how to set it up, in the words the web’s not_set_up problem gives — GitHub is not set up: no forge token was found; …, The forge is not set up: the base remote (upstream in a fork's clone, else origin), or a branch's push remote, does not name a repository on a forge; … — each labeled with its directory when several are named; neither changes the exit status |
reviews | one line per review, its number marked # (! on GitLab), or the JSON | “No pull requests are waiting on your review.” (“merge requests” on GitLab); “These are the first N; the forge holds more pull requests waiting on your review.” where the forge holds more than it lists, which does not change the exit status |
repositories | a line for where it works, then one per worktree and one per favorite, or the JSON | why the worktrees could not be read |
doctor | the report, or the JSON, and with no configuration file how to create one: the report is what a bug report pastes, so its guidance stays in it | |
config show | the configuration as JSON, credentials masked | the file it came from (# PATH); how to create one when there is none |
config init | with --dry-run, the file it would write, as JSON, masked | progress, the checks, “Wrote …”, what to do next, a warning when the file is not ignored by git |
summary | the summary as Markdown, or the JSON | with --post, to …, where it goes and how long the summary is against what the service takes; the dry-run line, “Not posted.”, “Posted to …”, each source left out as not set up — Taskwarrior is not set up, so it was left out: …, with how to set it up — and each source that could not be read |
issues | one line per issue — its key (a forge issue’s bare number), its summary and its status in parentheses — or the JSON | “No issues in VIEW.”, “Listed the first N of TOTAL issues in VIEW.” for a view longer than its first page, and “Not read: …” for each tracker that could not be read, which does not change the exit status |
issue | the issue in full — key and summary, type · status · priority, who reported it and who it is assigned to, its link, its description, and each comment’s author · date with its body indented — or the JSON | |
branch | Start work on KEY: create NAME from BASE and switch to it, then Created NAME; with --fetch the plan opens fetch REMOTE, then, naming the base remote (upstream in a fork’s clone, else origin); with --worktree it ends in a new worktree beside the repository, and the worktree’s directory follows alone on the last line | the dry-run line, “Not created.”, and with --worktree “Created NAME in a new worktree.” |
pr | Open TITLE, BRANCH → BASE — marked (draft) for a draft — and the reviewers asked, (code owners) unless --reviewer named them, a blank line, and the whole body; then Opened #N URL (!N on GitLab); with --json, the JSON alone | the dry-run lines, “Not opened.”, the offers to link it on the issue and to move the issue to the review status, and their outcomes; with messaging set up, “Announce it with workflow announce, or once CI passes with workflow announce –when-green.” once it is open; with --announce, the announcement’s preview and where it goes in place of that line, then what announce --when-green says as it waits; with --json, the preview and the Opened line too |
finish | Finish BRANCH: #N merged (!N on GitLab), then the three git commands it runs, each indented | the dry-run line, “Not finished.”, “Finished BRANCH: switched to BASE, caught it up and deleted BRANCH.” |
announce | the message and where it goes | that an earlier session already announced this moment, the dry-run line, “Not announced.”, “Announced to …”, then, when the store could not confirm it, “The store did not confirm it; it is not offered again.” and why, or “Already announced from another session; not posted again.” when another claimed it first; a warning, “Could not read what was announced (…); the store’s claim still keeps it from posting twice.”, when the store cannot be read; with --when-green, a line each time what it waits on changes — the forge not listing a pull request just opened yet, CI running, a check failed and it waits on a fix (one the post itself saw fail says so: “as it was to be posted”), no checks yet, a read that failed, a post that failed and is tried again — and “Stopped waiting; nothing was announced.” on ctrl+c |
comment | Comment on KEY: and the comment as the tracker will store it | the dry-run line, “Not posted.”, “Commented on KEY.” |
transition | Move KEY to STATUS (MOVE), the move the tracker offers | the dry-run line, “Left KEY as it is.”, “Moved KEY to STATUS.” |
assign | Assign KEY to USERNAME | the dry-run line, “Not assigned.”, “Assigned KEY to USERNAME.” |
worklog | Log DURATION on KEY, and the --comment note indented beneath it | the dry-run line, “Not logged.”, “Logged DURATION on KEY.” in Jira’s own words for the time |
slack login | the dry-run line, “Logged in to Slack as …” | |
db-clean | the store’s directory and each database file in it | the warning before --all removes kept.db, the dry-run line, “Nothing to remove.”, “Nothing removed.”, “Removed …” |
workflow --web | the address it serves on; with no configuration file, the ways to set one up (Settings, workflow config init); why the configuration did not load cleanly, and the cause of each failure it answers as internal, credentials masked |
So workflow config show | jq . parses, and workflow reviews | wc -l counts
reviews and nothing else.
What standard error says: levels and formats
What a command says on standard error is a log of entries, each a level:
- A note — a done, declined or dry-run line, guidance, what was left out — is the bare sentence, as it has always been.
- A warning — something asked for that did not happen, while the command
goes on: a post sent untagged, a pull request opened without every reviewer,
assignee or label asked, a link or a move after it that failed, a request
log not fully written — starts with the tag
WARN. - The error a command ends with starts with
ERROR, and is said once. - A debug line, only with
--verbose, starts withDEBUG.
On a terminal the tags are colored — WARN yellow, ERROR red, DEBUG
faint — and nothing else is. NO_COLOR, set to anything, turns the color
off, and CLICOLOR_FORCE=1 keeps it on a pipe.
Created feat/PROJ-412-fix-login in a new worktree.
WARN Not tagging anyone: the Slack token lacks the usergroups:read scope; add it to the Slack app, then run workflow slack login.
ERROR the Jira token was refused (401); run workflow doctor --onlineThree flags, accepted before or after any command, change what is said:
--quiet, or-q, leaves out every note, and keeps the warnings, the error and the questions a write asks.--verboseadds a debug line for each request the command makes, its service, method, path, status and how long it took, as--request-logwrites it:DEBUG jira GET /rest/api/2/myself 200 184ms. The terminal interface, which draws on the terminal standard error shares, says none;--request-logkeeps its requests instead.--quietand--verbosetogether are a mistake in the call, and exit 2.--log-formatsays it all astext(the default), or, for a log collector, asjson— one object a line — orlogfmt— one record a line. Each entry of those two is stamped with its time, which text never is, and the error carries the status the command exits with.
$ workflow --log-format json reviews
{"time":"2026-10-14T09:30:00Z","level":"info","msg":"No pull requests are waiting on your review."}
$ workflow --log-format logfmt config show
time=2026-10-14T09:30:00Z level=info msg="No .workflow.json found.\n\nCreate one with `workflow config init`.\nThen run `workflow doctor` to see what is still missing."
time=2026-10-14T09:30:00Z level=error msg="no .workflow.json found in /home/ana/src/api or /home/ana" exit_status=3The questions a write asks, and the guided config init’s conversation, are
said as they always were, whatever the flags: they are for the person
answering them.
JSON
--json, or -j, is on the reads: status, reviews, repositories, summary,
issues, issue and doctor; and on pr, for what it opened. config show prints JSON always. None of them carries a credential: config show masks
each to its last four characters, and the others never print one.
workflow status --json prints one object:
{
"issue": "PROJ-412",
"summary": "Fix token redaction",
"stages": [
{ "name": "Issue", "state": "done" },
{ "name": "Branch", "state": "done" },
{ "name": "Commits", "state": "done" },
{ "name": "Review", "state": "in_flight" },
{ "name": "Slack", "state": "not_started" }
],
"ci": "running"
}A stage’s state is done, in_flight, failed or not_started; ci is
running, passed, failed or none. The Review stage reads done once
CI has passed with no changes requested, or once the pull request has
merged; a merged one has no CI left to read, so ci is then none. The last
stage is named for the messaging service messaging.kind configures —
Slack, Teams, Discord or Webhook — so read the stages by position
rather than by that name. That stage reads done once the branch’s pull
request was announced at the moment it is at now — ready for review, or
merged — by announce or the interface, as the store remembers it; with
store.disabled it never does, nor for a pull request closed without merging,
which the loop no longer follows.
issue and summary are left out when the branch names no issue.
workflow status --json DIR… prints an array, one object per directory in
the order given, each with dir, the directory as it was given, and a
repository label: the name of the directory it leads to — . is named
for the directory the command runs in, .. for the one above — or, where
two directories given lead to directories of one name, each one’s path
written from your home. A directory that cannot be read has an error
instead of the stages — "not a git repository", or why its repository
could not be read — and the command then exits non-zero after printing the
whole array.
workflow reviews --json prints an array, oldest first, of the requests
GET /api/reviews answers (see Scripting the API):
opened_at is when each was opened, an RFC 3339 time, from which a script
works out how long it has waited, and is left out when the forge gave no time;
the line’s 3d is for reading. facets is the value each holds in the four
facets the terminal’s and the browser’s filter narrow the queue by — its
repository, its CI, draft or ready, and who asks — each with its label.
[
{
"author": "ana",
"ci": "passed",
"draft": false,
"facets": [
{"kind": "repository", "label": "acme/api", "value": "acme/api"},
{"kind": "ci", "label": "CI passed", "value": "passed"},
{"kind": "draft", "label": "ready", "value": "ready"},
{"kind": "author", "label": "by ana", "value": "ana"}
],
"number": 42,
"opened_at": "2026-10-05T09:12:00Z",
"repository": "acme/api",
"title": "fix(config): redact the webhook",
"url": "https://github.com/acme/api/pull/42"
}
]workflow repositories --json prints the object GET /api/repositories
answers (see Scripting the API):
here, where it runs (dir, shown — the path written from your home —
root, root_shown, within, origin, base — the host and path pull
requests merge into, present only in a fork’s clone — and config, the
configuration files that apply); worktrees, the repository’s working trees, the main one
first (dir, shown, branch, head, state — here, worktree or
missing — and locked), empty outside a repository; worktrees_error, why
they could not be read, or empty; favorites (dir, shown, state —
here, repository, directory or missing — and origin); and
favorites_kept, false when the store keeps nothing or under --dry-run. A
store whose favorites cannot be read lists none, and the command then exits
non-zero after printing.
workflow repositories --json | jq -r '.worktrees[0].dir'workflow issues --json prints the page GET /api/issues answers for the
same view (see Scripting the API):
issues, each with key, tracker — jira, or forge for the forge’s
issues, whose key is the bare number — summary, status,
status_category (new, indeterminate, done, or unknown for a
status Jira files under none of the three), type and, when
there is one, priority; total, how many the view holds; next, where
the page after this one starts, which GET /api/issues takes as after:
the last Jira issue listed and where Jira listed it, as PROJ-7@49, empty
when the page holds the whole view; and unavailable, each tracker that
could not be read. It is the view’s first page: its first 50 issues and, on
the first view when issues.forge is on, the issues assigned to you on the
repository’s forge ahead of them, which total counts too. A longer view’s
total says how many more there are.
{
"issues": [
{"key": "PROJ-7", "tracker": "jira", "summary": "Fix login", "status": "In Progress",
"status_category": "indeterminate", "type": "Bug", "priority": "High"}
],
"next": "",
"total": 1,
"unavailable": []
}workflow issue KEY --json prints the issue GET /api/issues/{key}
answers: the fields above, then reporter, assignee (left out when it is
unassigned), description, comments (author, body and, when the
tracker gave one, created, oldest first), comment_total and url, the
issue’s page in its tracker.
workflow issue PROJ-7 --json | jq -r '.comments[-1].body'workflow summary --json prints the object GET /api/activity answers
for the same period, read through the same seams, so a period gives the
same items, and names the same sources as unread or not set up, here, in the
Summary pane and in the web’s Summary section: from, to and today
(YYYY-MM-DD); sources, each source asked (source — git, tasks,
jira or forge — name, state, truncated and detail). state is
read; not_set_up, for a source with nothing set up to ask — no Jira or
forge token, no forge the base remote names, no Taskwarrior installed, no git
user.email — which is left out, its detail saying how to set it up; or
failed, for a source that is set up and could not be read, its detail
saying why. A detail never names a host; years, the items nested by months, days and
hours, each item with at, source, verb, ref, title, url and
repository; and text, the same as Markdown. --from and --to name the
first and last day, written YYYY-MM-DD; one alone is that day, and neither
is the previous working day — yesterday, or on a Monday the Friday and the
weekend after it. A source that could not be read is named in sources, and
the command then exits non-zero after printing, with the first family its
failures belong to: a Jira token refused exits 3. A source that is not set up
is left out, with a note on standard error, and does not change the exit
status: with nothing else wrong, summary exits 0.
workflow summary --from 2026-10-01 --to 2026-10-02 --json | jq -r '.years[].months[].days[].hours[].items[].title'workflow pr --json prints what it opened as one object, the web’s
OpenedPullRequest with the branches the pull request joins and its
body, and with whether each offer that followed was taken:
{
"pull": {
"number": 7,
"url": "https://github.com/acme/api/pull/7",
"title": "fix(config): redact the webhook",
"draft": false,
"head": "fix/PROJ-412-redact",
"base": "main",
"body": "## Summary\n\nRedact the webhook URL.\n\nPROJ-412\n"
},
"follow_ups": [
{ "action": "link", "issue_key": "PROJ-412", "done": true },
{ "action": "transition", "issue_key": "PROJ-412", "status": "In Review", "done": true }
]
}warning is added when the pull request opened but some of its reviewers,
assignees or labels could not be added. follow_ups lists the offers made —
none when the branch names no Jira issue — and done is false for one
declined or one that failed; one that failed is warned of on stderr, and the
command still exits 0, since the pull request is open.
Under --dry-run it prints the pull request it would open, with number
0, url empty and every offer not done. A pull request that was not
opened — declined, refused or failed — prints nothing.
workflow doctor --json prints the report as an object: version; repository
(inside_work_tree, root, branch, detached, remote, forge — the
base remote’s forge — and, in a fork’s clone only, base_remote and base, its
name and address; or, outside a work tree, problem: that git is not on PATH, that the directory is in no
work tree, or that the working directory cannot be read);
tooling, one entry per program (name, found, required, effect, and
detail where finding it took more than a look at PATH: the Taskwarrior
version and path found, or why none is usable);
store (dir, where the store keeps its files; disabled, true when
store.disabled turned it off; or problem, why no data directory could be
found, which leaves the store keeping nothing);
configuration (path, the file a save writes; files, every file read,
the home directory’s before the repository’s; tracker — jira, or forge when no jira.base_url
leaves the forge’s issues as the tracker — jira_url, jira_auth_mode,
messaging_target, messaging_mode, world_readable, then missing and
problems: the required fields still empty and the values filled in wrong, each
null when there are none), or config_problem when the file did not load; and
credentials (checked, and with --online over a file that loaded,
results: service, status — ok, missing, rejected, unreachable or
unchecked — and detail). It exits as the prose report does: a field missing,
a value filled in wrong or a file other users can reach exits 3. A rejected
credential is one the service refused. A credential that is missing — none
configured, or a keychain item, token_command or token_env that gave
none — exits 3 as a
rejected one does, though it was never put to the service. A service that
answers with a redirect, or asks you to wait, is unreachable and exits 5: it
never judged the credential. A check doctor could not make is unchecked and
counts toward no exit status: a webhook, which only posting would test; Jira
when the forge’s issues are the tracker, since there is no Jira to ask; and a
forge it cannot name — no repository remote, or a host other than
github.com, a ghe.com tenant or gitlab.com with no forge.kind and
forge.host for it. A jira.base_url that is not an https address, or http to
this machine, or that carries a login, and a forge.kind that names neither
forge, are refused when the file loads, so they fail the configuration and
nothing is checked.
workflow config show prints the configuration file’s own shape, as
Configuration describes it.
Writing without a person: --yes and --dry-run
branch, pr, finish, announce, comment, transition, assign, worklog,
summary --post and db-clean print a preview and ask before they write. Two
flags change that, each spelled the same short way on every command that takes it:
--yes(-y) goes ahead without asking. Onprit answers every question: the push, the open, and the offers that follow it — to link the pull request on the branch’s issue and to move the issue to the review status. Once the pull request is open, what fails after it is a warning on stderr and the command exits 0: a reviewer, assignee or label that could not be added, and a link or a move that failed — a link that fails still leaves the move to be made. Onannounceit never repeats an announcement: when the store says this pull request was already announced at the moment it is at, it says so on stderr, announces nothing, and exits 0 — run without--yesto be asked. With--dry-runas well, it still prints the announcement, and its dry-run line says it would not announce it again. Nor does it announce a pull request a check failed on:announcereads its CI before it previews anything, under--dry-runtoo, and exits 4 naming the checks that failed and the way on —--when-greenfor a pull request ready for review, and re-running the failed checks on the forge for a merge, which has no CI to wait for; a CI it cannot read exits as that read failed (5 for a forge it could not reach). With--when-greenit waits instead, in the foreground:--yesanswers the one question before the wait, which reads CI everytiming.ci_interval, through a failed run, and announces once a run passes. It reads the pull request of the branch it started on, whatever is checked out meanwhile. It exits 4 for a pull request that has merged (no CI to wait for), one that reports no check across ten minutes of reads that were heard, counted from the last that saw one, a read that failed not counting (announce a repository with no CI by hand), one whose CI runs and reads the same — no check finished, failed or started — for two hours (CI on #7 has been running for 2h; not announced), and one that merges first or is no longer the branch’s — closed counts. Reads of CI that fail, a forge that does not list a pull request just opened yet, and posts the store cannot claim or the service asks to wait are tried again an interval on, for ten minutes from the first since one was heard, then given up on, exiting as what failed last does: 3 for a credential refused, 5 for a service it could not reach or that asked it to wait, and 4 otherwise. A post the service refused gives up at once, exiting as that refusal does; one the service did not answer, or failed while taking (Slack’sinternal_error,fatal_error,service_unavailableorrequest_timeout), may have gone out, so it is not tried again: onlyannounce, asked whether to announce it again, posts it again.ctrl+cstops it, announcing nothing, with 130. Its dry run says it would announce once CI passes, and waits for nothing.pr --announcedoes the same once the pull request is open, whatever failed after it, asking nothing more, after printing the--jsonreport when asked for one, and reads the forge again until it lists the pull request it just opened, for up to ten minutes; without messaging set up it opens nothing and exits 3, and beside--draft, a pull request never announced, it opens nothing and exits 2. Onsummaryit answers only--post’s question, so it is refused without--post. A summary is posted even when a source could not be read — the text says which — and the command still exits non-zero for it.--dry-run(-n) prints the preview and what the command would do, and writes nothing, the store included:announcestill reads what an earlier session announced, when there is a store on disk, but never creates it or changes what it holds (SQLite may leave its two companion files,-waland-shm, beside it until the next session). Whatprwould do is a line for the push and the open, then one for each offer the open would lead to —dry run: would link it on KEYanddry run: would move KEY to STATUS. It is one flag for every command, given before the command’s name or after it:workflow --dry-run pr,workflow pr --dry-runandworkflow pr -nare the same.config init --dry-runruns its checks and prints the file it would write, masked, without writing it or storing anything in the keychain. Bareworkflow --dry-runis the interface with every write held back.
A write run without --yes and without a terminal — stdin piped or closed —
has no way to be answered, so it stops, says to pass --yes, and exits 2.
comment reads its text from stdin to the end, so piped it always needs
--yes; at a terminal, end the text with Ctrl+D and the question is asked
after it. The guided config init, with nothing to answer its questions,
stops the same way and exits 2, saying to pass --template, which writes a
file to edit by hand without asking. Two
exceptions say to run it at a terminal instead: announce at a moment already
announced, which --yes would leave as it is, and slack login, which takes
no --yes because what it asks for are secrets. Questions and troubleshooting:
Scripting and automation answers what
a run in CI most often meets.
Posting elsewhere: --channel
announce and summary --post post in messaging.channel. With a Slack user
token, --channel CHANNEL posts the one message in CHANNEL instead — the
preview’s to line, and the line that says it was posted, name it. A webhook
posts only to the channel it was made for, so there --channel exits 2.
What the store remembers is still the pull request at its moment, wherever it
was announced: once announced in one channel, announce --yes --channel
leaves it as it is, as it would in the same channel.
Choosing what pr opens
pr opens the pull request it composes, as the interface does, unless its
flags say otherwise; each stands for an edit the terminal’s composer and the
web’s form allow:
--title TEXTis the title in place of the one composed.--body TEXTis the whole description, in place of the one composed from the repository’s template, the commits and the issue’s link.--template NAMEstarts the description from the repository’s template of that name rather than its first, asctrl+tin the composer and the form’s Template do. A name the repository has no template of exits 1, naming the templates it has; beside--body, which leaves a template nothing to start, it exits 2.--base BRANCHmerges it into another branch, and drafts it againstBRANCH: the title and body come from the branch’s commits pastBRANCH, andBRANCH’s code owners are asked to review, as the composer and the form draft again when their base is edited.BRANCHis read on the base remote when it holds one, else as a local branch. A name git would refuse for a branch exits 2 before anything is read; a name no branch has exits 1.--reviewer NAMEasksNAMEto review in place of the code owners;org/teamasks a team. Repeat it, or separate names with commas.--draftopens it as a draft: the preview marks the branches(draft), and the question asks to open the draft pull request.
--json reports what was opened, base and draft among it.
A log for a bug report: --request-log
--request-log FILE appends a one-line outline of every request a command makes —
the time, the service, the method, the path, the status and how long it took
— to FILE. Like --dry-run, it is accepted before or after any command.
It records nothing else: never a header, a body, a query string or a host,
and never the path of a messaging webhook — Slack’s, Teams’, Discord’s or a
plain one — which is itself the credential. The file is created readable only
by you. A line that cannot be written — on a full disk, say — neither stops
the command nor changes its exit status: as it ends, the command says once on
stderr that the request log could not be fully written. Its old name,
--log, is refused, exit 2, naming the new one. --verbose says the same
outlines on stderr as debug lines, beside the file or without one.
2026-09-22T18:04:11Z jira GET /rest/api/2/myself 200 184msworkflow --request-log requests.log doctor --online is the run a bug report
most wants: every credential check, each under its service’s name.