workflow

Install

Mon, 01 Jan 0001 00:00:00 +0000

Install

What it needs

git, always.
lefthook, for running hooks on demand and for turning existing .git/hooks into a lefthook.yml. Without it those two actions are not offered; commits still run whatever hooks git has.
gh, optionally, as a place to find a GitHub token. See Configuration.

With Go

The shortest path, if you have Go installed:

go install github.com/jacob-delgado/workflow/cmd/workflow@latest

The binary lands in $(go env GOPATH)/bin, which needs to be on your PATH:

workflow

Mon, 01 Jan 0001 00:00:00 +0000

workflow

Run your Jira, Git forge and messaging workflow from the terminal

Synopsis

workflow ties Jira, your Git forge and your team’s messaging service into one terminal workflow.

CONFIGURATION

workflow reads .workflow.json from the current directory, and falls back to your home directory. A file in the current directory REPLACES the one in your home directory — the two are never merged, so a repository-local configuration is always the whole story.

Using workflow

Mon, 01 Jan 0001 00:00:00 +0000

Using workflow

Run workflow inside a repository. It opens on the issues assigned to you and reads everything else — the branch, its changes, its pull request, its CI — from the repository and the services it talks to. Where you are in the work is worked out from the branch name each time, never stored. A small on-disk store does remember a few conveniences between sessions — the commit scope you last used, what you have announced, the last issue list — under your platform’s data directory and never a secret; set store.disabled to true to keep nothing on disk.

The web interface

Mon, 01 Jan 0001 00:00:00 +0000

The web interface

workflow --web serves the same loop in a browser: the same issues, branch, pull request and announcement the terminal interface shows, read from the same repository and services through the same code. It is another way in, not a second implementation, and the terminal stays the fuller of the two.

Start it

workflow --web # serve http://127.0.0.1:7000
workflow --web --dry-run # the same, read-only

Run it inside a repository, then open http://127.0.0.1:7000. It listens on the loopback interface alone, on port 7000, and refuses a write from a page served anywhere else, so a site open in another tab cannot drive it. ctrl+c in the terminal stops it.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration

workflow reads a single JSON file, .workflow.json.

{
 "jira": {
 "base_url": "https://jira.example.com",
 "token": "",
 "user": ""
 },
 "messaging": {
 "kind": "slack",
 "token": "",
 "webhook_url": "",
 "channel": "#dev-workflow"
 },
 "forge": {
 "kind": "",
 "host": "",
 "token": ""
 },
 "ui": {
 "mouse": true,
 "ascii": false,
 "color": ""
 }
}

Run workflow config init and it asks for the Jira address and token, checks them, does the same for Slack, warns if the file would not be ignored by git, and writes what passed — nothing is echoed as you type a token. Add --global to write it to your home directory, or --template to write a blank file to fill in by hand instead of being asked.

workflow announce

Mon, 01 Jan 0001 00:00:00 +0000

workflow announce

Announce the branch’s pull request to your team’s chat

Synopsis

Announce what the messaging pane would — the branch’s pull request, its issue, and where it stands (ready for review, merged, or CI red) — to the configured Slack, Teams, Discord or webhook. A preview is printed and confirmed before anything is announced.

What it announces is remembered, with what the interface announces: a pull request already announced at the moment it is at is said to be, and asked about again rather than repeated — with –yes, it is left as it is.

workflow branch

Mon, 01 Jan 0001 00:00:00 +0000

workflow branch

Branch for an issue, named by the convention, and switch to it

Synopsis

Name a branch for an issue the way the interface does — from the issue’s type and summary — then create it off the current branch’s base and switch to it, which moves the working tree onto the new branch. A preview is printed and confirmed before anything is created.

workflow branch <issue> [flags]

Options

 -h, --help help for branch
 --yes go ahead without the confirmation

Options inherited from parent commands

 --dry-run hold back every write to Jira, the forge, the messaging service, git and files, and say what it would have done
 --log string append a one-line outline of each request (method, path, status, duration) to FILE, for a bug report

workflow completion

Mon, 01 Jan 0001 00:00:00 +0000

workflow completion

Generate the autocompletion script for the specified shell

Synopsis

Generate the autocompletion script for workflow for the specified shell. See each sub-command’s help for details on how to use the generated script.

Options

 -h, --help help for completion

Options inherited from parent commands

 --dry-run hold back every write to Jira, the forge, the messaging service, git and files, and say what it would have done
 --log string append a one-line outline of each request (method, path, status, duration) to FILE, for a bug report

workflow config

Mon, 01 Jan 0001 00:00:00 +0000

workflow config

Create and inspect the configuration file

workflow config [flags]

Options

 -h, --help help for config

Options inherited from parent commands

 --dry-run hold back every write to Jira, the forge, the messaging service, git and files, and say what it would have done
 --log string append a one-line outline of each request (method, path, status, duration) to FILE, for a bug report

workflow doctor

Mon, 01 Jan 0001 00:00:00 +0000

workflow doctor

Report the repository, tooling, and configuration in effect

Synopsis

Report the git repository this session is in, which external programs are installed, which .workflow.json is in effect, and which required fields are still empty.

Makes no network calls by default, so it is safe to run anywhere and tells you only that a credential is present. Add –online to ask each service whether the credential actually works. Add –json for the same facts as data, with the same masking.

workflow pr

Mon, 01 Jan 0001 00:00:00 +0000

workflow pr

Open a pull request for the current branch

Synopsis

Compose a pull request for the checked-out branch from its commits, the issue and the repository’s template — the same as the interface — pushing the branch first when it is not yet on its remote. A preview is confirmed first.

Once it is open, it offers — as the interface does — to link it on the branch’s issue, then to move the issue to the review status (jira.review_status).

workflow reviews

Mon, 01 Jan 0001 00:00:00 +0000

workflow reviews

List the pull requests that are waiting on your review

Synopsis

List the open pull or merge requests on your forge that request your review, oldest first, with the author, how CI stands and how long each has been waiting. The forge is the one your repository’s remote points at.

workflow reviews [flags]

Options

 -h, --help help for reviews
 --json print the reviews as JSON

Options inherited from parent commands

 --dry-run hold back every write to Jira, the forge, the messaging service, git and files, and say what it would have done
 --log string append a one-line outline of each request (method, path, status, duration) to FILE, for a bug report

workflow standup

Mon, 01 Jan 0001 00:00:00 +0000

workflow standup

Draft what you did — commits, issues and pull requests — to share

Synopsis

Gather the commits you made, the issues you touched and the open pull requests on your branches over the last day, open the draft in your editor, and offer to post it to your team’s chat. Nothing is posted until you confirm; –yes posts without asking, and –dry-run prints the draft and posts nothing. –yes does not skip the editor: add –no-edit to run it unattended.

workflow status

Mon, 01 Jan 0001 00:00:00 +0000

workflow status

Print the current work’s issue, stage and CI on one line

Synopsis

Print, on one line, the issue the branch is for, how far along the loop the work has got, and how CI stands — the same progress the interface’s top row shows, for a shell prompt or a status bar. –json prints it as data.

Given one or more directories, it prints a labeled line for each, so workflow status ~/src/* reports every repository at once. Each reads its own configuration. A directory that cannot be read still gets its line, saying why, and the command then fails, as it does outside a repository.

Scripting

Mon, 01 Jan 0001 00:00:00 +0000

Scripting

The steps of the loop that a script or a shell prompt wants also run as commands, without the interface: status, reviews, standup, branch, pr and announce, beside doctor and config. 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.

Web API errors

Mon, 01 Jan 0001 00:00:00 +0000

Web API errors

The workflow --web API answers a failed request with an RFC 9457 problem details object, sent as application/problem+json. (The loopback, same-origin and dry-run guards refuse a request as plain text before it reaches the API, so those few responses are not problem details.)

{
 "type": "https://jacob-delgado.github.io/workflow/docs/errors/#not-found",
 "title": "Not found",
 "status": 404,
 "detail": "issue PROJ-412 was not found",
 "code": "not_found"
}

type — a stable URI naming the problem; it points at the matching section below.
title — a short, fixed summary of the problem type.
status — the HTTP status code.
detail — what went wrong this time, safe to show. It is curated: it never carries a secret (tokens are redacted before an error is formed) or an internal host. A write that is refused may include the git or forge’s own reason so you can act on it; a read failure and an unreachable upstream stay generic.
code — a stable, machine-readable reason, for a client to switch on rather than parsing prose.

The codes below are the whole set.

Development

Mon, 01 Jan 0001 00:00:00 +0000

Development

The full contributor guide lives in CONTRIBUTING.md, and the code standards in CLAUDE.md. This page is the shape of the thing.

Setup

git clone https://github.com/jacob-delgado/workflow.git
cd workflow
mise trust && mise install # the whole toolchain, at pinned versions
task setup # modules + git hooks

mise is the only thing you install by hand. Every other tool — Go and the task runner, every linter and formatter, the coverage and security scanners, the docs builder — is pinned in mise.toml at an exact version. That file is the single source of truth, and the list: the build container reads it, and so does CI, so a developer’s machine, the container, and CI cannot drift apart. Naming each tool here would only drift from it.

workflow completion bash

Mon, 01 Jan 0001 00:00:00 +0000

workflow completion bash

Generate the autocompletion script for bash

Synopsis

Generate the autocompletion script for the bash shell.

This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager.

To load completions in your current shell session:

source <(workflow completion bash)

To load completions for every new session, execute once:

Linux:

workflow completion bash > /etc/bash_completion.d/workflow

macOS:

workflow completion bash > $(brew --prefix)/etc/bash_completion.d/workflow

You will need to start a new shell for this setup to take effect.

workflow completion fish

Mon, 01 Jan 0001 00:00:00 +0000

workflow completion fish

Generate the autocompletion script for fish

Synopsis

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

workflow completion fish | source

To load completions for every new session, execute once:

workflow completion fish > ~/.config/fish/completions/workflow.fish

You will need to start a new shell for this setup to take effect.

workflow completion fish [flags]

Options

 -h, --help help for fish
 --no-descriptions disable completion descriptions

Options inherited from parent commands

 --dry-run hold back every write to Jira, the forge, the messaging service, git and files, and say what it would have done
 --log string append a one-line outline of each request (method, path, status, duration) to FILE, for a bug report

workflow completion powershell

Mon, 01 Jan 0001 00:00:00 +0000

workflow completion powershell

Generate the autocompletion script for powershell

Synopsis

Generate the autocompletion script for powershell.

To load completions in your current shell session:

workflow completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

workflow completion powershell [flags]

Options

 -h, --help help for powershell
 --no-descriptions disable completion descriptions

Options inherited from parent commands

 --dry-run hold back every write to Jira, the forge, the messaging service, git and files, and say what it would have done
 --log string append a one-line outline of each request (method, path, status, duration) to FILE, for a bug report

workflow completion zsh

Mon, 01 Jan 0001 00:00:00 +0000

workflow completion zsh

Generate the autocompletion script for zsh

Synopsis

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(workflow completion zsh)

To load completions for every new session, execute once:

workflow config init

Mon, 01 Jan 0001 00:00:00 +0000

workflow config init

Set up the configuration file, asking for and checking each credential

Synopsis

Ask for the Jira and Slack credentials, check each one, and write a .workflow.json with what passed.

By default it lands at the repository root, so every subdirectory sees it; outside a repository it lands in the current directory. Use –global to write it to your home directory instead, where every directory can see it. Use –template to write a blank file to fill in by hand rather than being asked. With –dry-run it runs the same checks, writes nothing and stores nothing in the keychain, and prints the file it would write, masked.

workflow config show

Mon, 01 Jan 0001 00:00:00 +0000

workflow config show

Print the configuration in effect, with tokens masked

Synopsis

Print the configuration in effect as JSON, with every credential masked. The JSON alone goes to stdout, so it pipes into jq; the file it came from is named on stderr. With no configuration file it says how to create one and fails, as doctor does.

workflow config show [flags]

Options

 -h, --help help for show

Options inherited from parent commands

 --dry-run hold back every write to Jira, the forge, the messaging service, git and files, and say what it would have done
 --log string append a one-line outline of each request (method, path, status, duration) to FILE, for a bug report

workflow

Install

Install

What it needs

With Go

workflow

workflow

Synopsis

Using workflow

Using workflow

The web interface

The web interface

Start it

Configuration

Configuration

workflow announce

workflow announce

Synopsis

workflow branch

workflow branch

Synopsis

Options

Options inherited from parent commands

SEE ALSO

workflow completion

workflow completion

Synopsis

Options

Options inherited from parent commands

SEE ALSO

workflow config

workflow config

Options

Options inherited from parent commands

SEE ALSO

workflow doctor

workflow doctor

Synopsis

workflow pr

workflow pr

Synopsis

workflow reviews

workflow reviews

Synopsis

Options

Options inherited from parent commands

SEE ALSO

workflow standup

workflow standup

Synopsis

workflow status

workflow status

Synopsis

Scripting

Scripting

Web API errors

Web API errors

Development

Development

Setup

workflow completion bash

workflow completion bash

Synopsis

Linux:

macOS:

workflow completion fish

workflow completion fish

Synopsis

Options

Options inherited from parent commands

SEE ALSO

workflow completion powershell

workflow completion powershell

Synopsis

Options

Options inherited from parent commands

SEE ALSO

workflow completion zsh

workflow completion zsh

Synopsis