DEVELOPER TOOLS

CLI

Updated October 24, 2026 · 9 min read
The devflow command runs DevFlow’s actions from your terminal. It works out the project, issue and repository from the folder you’re in, so most commands only need their own arguments.
A terminal running DevFlow CLI commands

01Install

Needs Node.js 20 or newer.
1
Keep DevFlow running
DevFlow Desktop must run in the tray and Chrome must be open with the DevFlow extension. The extension does the work with your saved settings, so there are no tokens to copy.
2
Install the CLI
Run npm i -g @devflow-one/cli, then devflow --help to list every command.
3
Check what it sees
Run devflow where inside a repository. It shows the project, issue, repository and Chrome profile it found, and where each one came from.

02Global flags

They work with every command that runs an action. Write them as --flag value or --flag=value.
FLAGWHAT IT DOESVALUE
--issuePicks the Jira issue. Its prefix picks the project, and commands that take an issue key use it too.Issue key, e.g. ABC-123
--projectPicks the Jira project directly.Project key
--profileSends the action to this Chrome profile when several are connected.Profile id
--repoPicks the repository when the project has several. It can’t pick the project on its own.Repository id or URL
--force, --yesConfirms a destructive command. Without one of them it is refused.None
--jsonPrints machine-readable JSON instead of text.None
--helpPrints usage and exits.None
--Everything after it counts as an argument, even if it starts with --.None
list-actions and list-profiles ignore --issue, --project, --profile and --repo.

03Environment variables

Set these instead of passing the same flags every time.
VARIABLEWHAT IT DOESVALUE
DEVFLOW_PROJECT, DEVFLOW_ISSUE, DEVFLOW_REPO, DEVFLOW_PROFILEDefault project, issue, repository and profile. Flags win over them.Same as the flag
DEVFLOW_GATEWAY_PORTPort DevFlow Desktop listens on.Default 8787
DEVFLOW_GATEWAY_TOKENToken to use instead of reading the token file. It changes every time DevFlow Desktop restarts, so the file is the better choice.Token
DEVFLOW_GATEWAY_DATA_DIRFolder to read the token file from.Folder path
DevFlow Desktop writes the token file to ~/Library/Application Support/devflow on macOS, ~/.config/devflow on Linux and %APPDATA%\devflow on Windows.

04How it finds the project

Each value comes from the first source that has it, and a later source never replaces it. The project key is the part of the issue key before the last dash. DevFlow never guesses: if two projects match, pass --project or --repo.
1
Flags
--issue, --project, --repo and --profile win over everything else.
2
Environment variables
The DEVFLOW_PROJECT, DEVFLOW_ISSUE, DEVFLOW_REPO and DEVFLOW_PROFILE values.
3
Git remote
The folder’s origin remote is matched against your repositories in Settings. That gives the project, repository and profile.
4
Checkout folder
The folder is matched against each repository’s local path in Settings.
5
Branch name
An issue key in the branch name — feature/ABC-123-login gives ABC-123.
6
Folder name
A parent folder named like an issue key, e.g. ~/work/ABC-123/src.

05Issues

Read-only, and default to the issue found from your branch or folder. Issue status needs the Jira API token set in Settings.
Issue status
devflow issue status
Shows the issue’s Jira status and its parent’s, as the panel’s status bar does. Needs the Jira API token set in Settings. Read-only.
NAMETYPEREQUIREDDESCRIPTION
[issueKey]issue key—Issue to look up. Falls back to --issue, then to the issue found from your branch or folder. Fails if there is none.
Example:
devflow issue status ABC-123
Issue branches
devflow issue branches
Lists each repository’s remote branches for the issue, and for its parent when the repo card includes it. Read-only.
NAMETYPEREQUIREDDESCRIPTION
[issueKey]issue key—Issue to look up. Falls back to --issue, then to the issue found from your branch or folder. Fails if there is none.
Example:
devflow issue branches
Issue pull requests
devflow issue prs
Lists each repository’s pull requests for the issue in every state, merged and closed included, with approvers on open ones — the same list the repo card shows. Read-only.
NAMETYPEREQUIREDDESCRIPTION
[issueKey]issue key—Issue to look up. Falls back to --issue, then to the issue found from your branch or folder. Fails if there is none.
Example:
devflow issue prs

06Branches

The repository’s branch template always decides the branch name.
Create branch
devflow branch create
Creates the issue’s branch, or reuses it if it already exists. The template decides the name, so a sub-task may share its parent’s branch. Needs an issue key or a branch name. If it times out, check whether the branch exists before you retry.
NAMETYPEREQUIREDDESCRIPTION
[branchName]text—Fallback name, used only when the template can’t be applied. Its issue key is used when you don’t pass --issue.
--issueissue key—Issue whose branch to create. Defaults to the issue found from your folder, but only when you give no branch name.
--frombranch—Existing remote branch to start from. Defaults to the repository’s base branch. Refused without a value.
Example:
devflow branch create --issue ABC-124 --from release/2026.4
Resolve branch name
devflow branch resolve
Shows the branch an issue’s work belongs on and whether it exists yet. Run it before you create a branch, commit or open a pull request. Read-only.
NAMETYPEREQUIREDDESCRIPTION
[issueKey]issue key—Issue to look up. Falls back to --issue, then to the issue found from your branch or folder. Fails if there is none.
Example:
devflow branch resolve ABC-124
Delete branch
devflow branch delete
Deletes a branch in the project’s repository. Destructive, so it needs --force or --yes. If it times out, check the branch before you retry.
NAMETYPEREQUIREDDESCRIPTION
branchNametextBranch to delete.
--forceflagConfirms the delete. --yes works too.
Example:
devflow branch delete old-login --project ABC --force

07Commits

The default commit template is the summary, then the list of changes, then the issue slug.
Commit by template
devflow commit template
Commits a folder with the project’s commit template, then pushes to origin. In a DevFlow-managed copy it stages every changed or deleted tracked file; in your own checkout it commits only what you already staged. It commits whichever branch is checked out and won’t push from the base branch. Pushing is destructive, so it needs --force, or --no-push for a local commit. If it times out, it may already have committed or pushed.
NAMETYPEREQUIREDDESCRIPTION
worktreePathfolderFolder to commit: a DevFlow-managed copy or the repository’s local path from Settings. Any other folder is refused.
--valuesJSON object—Values for the template: summary (the subject line), changesList (a list, written as bullets), issueSlug and prNumber. Custom templates can use other keys. Empty values still commit and are shown as warnings.
--include-untrackedflag—Also stages new files that aren’t ignored.
--no-pushflag—Commits locally without pushing. Then --force isn’t needed.
--forceflagConfirms the push. Not needed with --no-push. --yes works too.
Example:
devflow commit template ~/work/ABC-123 --values '{"summary":"Fix login"}' --force

08Pull requests

Merge requests on GitLab. Commands that take a pull request use its number, e.g. 42.
Create draft pull request
devflow mr create
Opens a pull request from the issue’s branch, always as a draft. The PR type fills the title, description and labels from its templates; if a template can’t be filled, your title and body are used and the reason is shown as a warning. Needs a title plus an issue key or a branch. If it times out, run devflow mr find before you retry — the pull request may already exist.
NAMETYPEREQUIREDDESCRIPTION
titletextPull request title.
[headBranch]branch—Source branch. A branch that exists on the remote is used as is; otherwise the issue’s branch from the template is used.
--issueissue key—Ties the pull request to the issue for the templates. Defaults to the issue found from your folder or from headBranch. The issue title needs the Jira API token in Settings.
--bodytext—Fallback description, used when the PR type template (which uploads media via its own {prMedia}) can’t be filled; {prMedia} here is filled or removed. Empty by default. Always give it a value: a bare --body isn’t refused and is sent as true.
--basebranch—Target branch. Defaults to the repository’s base branch; a pattern like {year}/{number} picks the newest matching branch. Refused without a value.
--typeid or label—PR type. Picked from the title prefix, branch prefix, Jira issue type or title words, else the first type. See devflow mr types. Refused without a value.
Example:
devflow mr create "Fix login" --issue ABC-123 --type Fix
Mark ready for review
devflow mr ready
Takes a draft pull request out of draft. Also applies the PR type's labels, assigns you if no one is assigned and asks the type's missing reviewers. To refresh these later, run devflow mr draft and then this again.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
--typeid or label—Switches the PR type, swapping its labels. See devflow mr types. Refused without a value.
Example:
devflow mr ready 42 --type Fix
Mark as draft
devflow mr draft
Turns a pull request back into a draft.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
Example:
devflow mr draft 42
Close pull request
devflow mr close
Closes a pull request without merging. Destructive, so it needs --force or --yes. If it times out, check the pull request before you retry.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
--forceflagConfirms the close. --yes works too.
Example:
devflow mr close 42 --force
Merge pull request
devflow mr merge
Merges a pull request. If the provider says no — conflicts, missing approvals, a protected branch — it fails with the provider’s reason. Destructive, so it needs --force or --yes. If it times out, check the pull request before you retry.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
--methodtext—merge, squash or rebase. Defaults to the provider’s setting. Anything else is refused.
--delete-source-branchflag—Deletes the source branch after the merge.
--forceflagConfirms the merge. --yes works too.
Example:
devflow mr merge 42 --method squash --delete-source-branch --force
Assign
devflow mr assign
Assigns a pull request to a user.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
assigneeusernameUser to assign.
Example:
devflow mr assign 42 jdoe
Find by issue
devflow mr find
Finds the pull request for an issue. Read-only.
NAMETYPEREQUIREDDESCRIPTION
[issueKey]issue key—Falls back to --issue, then to DEVFLOW_ISSUE, then to the issue found from your branch or folder.
Example:
devflow mr find
Get pull request
devflow mr get
Shows a pull request’s title, description, link, state, draft flag, and source and target branch. Read-only.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
Example:
devflow mr get 42
Update pull request
devflow mr update
Changes the title, description or target branch, then shows the pull request as saved. Pass at least one change. --description and --append-description can’t be used together. To refresh videos and screenshots, swap the old media links for {prMedia}: DevFlow uploads .devflow/media/<ISSUE-KEY>[-n].{mp4,png,jpg,jpeg} and puts the new links there. If the upload fails or the branch names no issue, {prMedia} is removed and media.error says why.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
--titletext—New title. A blank title is refused.
--descriptiontext—Replaces the whole description, exactly as given.
--append-descriptiontext—Adds text after a --- line. Skipped if the description already ends with it, so running it twice is safe.
--basebranch—New target branch. It must exist on the remote.
Example:
devflow mr update 42 --append-description "## Test plan"
List PR types
devflow mr types
Lists the repository’s PR types with their id, label and which one is the default. Empty if none are set up. Read-only.
Example:
devflow mr types --project ABC
Get fix-comments prompt
devflow mr fix-prompt
Prints the prompt DevFlow uses to fix review comments: the base prompt plus your project’s fix rules. It runs no AI and changes nothing.
NAMETYPEREQUIREDDESCRIPTION
[prId]number—Pull request the prompt is for.
--issueissue key—Issue the prompt is for. Defaults to the issue found from your folder.
Example:
devflow mr fix-prompt 42
Review comment counts
devflow mr comments
Counts a pull request’s review comments as the Fix Comments row does: unfixed, fixed, resolved and PR-level comments. Read-only.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
Example:
devflow mr comments 42
Fix comments
devflow mr fix-comments
Starts an AI fix of the pull request’s review comments in the repository’s local folder, like Fix Comments in the panel. The run commits and pushes, so it’s destructive and needs --force or --yes. It returns at once with started, prNumber and queued, which is true when an automation run is busy and the fix starts on its next tick. It returns started: false with a reason while the panel or the timer is already fixing that pull request. Run devflow mr comments later to see the counts change.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberOpen pull request to fix.
--forceflagConfirms the run. --yes works too.
Example:
devflow mr fix-comments 42 --force
Reply as fixed
devflow mr reply-fixed
Replies “Fixed” to every unanswered review thread, like Reply as Fixed in the panel, and resolves each one when the repository is set to. Prints how many replies worked and failed. If it times out, check the counts before you retry.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
Example:
devflow mr reply-fixed 42

09Pipelines

Pipelines on GitLab, workflow runs on GitHub.
Pipeline status
devflow pipeline status
Shows the pipeline status for a pull request’s latest commit. Read-only.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
headShacommit SHAThe pull request’s latest commit.
Example:
devflow pipeline status 42 deadbeef
List pipeline jobs
devflow pipeline jobs
Lists the pipeline jobs for a pull request’s latest commit. Read-only.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
headShacommit SHAThe pull request’s latest commit.
Example:
devflow pipeline jobs 42 deadbeef
Restart failed jobs
devflow pipeline retry
Restarts only the failed jobs of a pipeline or run — what pipeline retry does by default. If it times out, check the pipeline before you retry.
NAMETYPEREQUIREDDESCRIPTION
pipelineOrRunIdnumberPipeline id on GitLab, run id on GitHub.
Example:
devflow pipeline retry 555
Restart all jobs
devflow pipeline retry --all
Restarts every job of a pipeline or run. If it times out, check the pipeline before you retry.
NAMETYPEREQUIREDDESCRIPTION
pipelineOrRunIdnumberPipeline id on GitLab, run id on GitHub.
--allflagRestarts all jobs instead of only the failed ones.
Example:
devflow pipeline retry 555 --all
Restart one job
devflow pipeline retry --job
Restarts a single job. With --job the pipeline id isn’t needed and is ignored. If it times out, check the job before you retry.
NAMETYPEREQUIREDDESCRIPTION
--jobnumberId of the job to restart.
Example:
devflow pipeline retry --job 9876

10Slack

Messages are posted from your own Slack account.
Notify Slack
devflow slack notify
Sends a message to the project’s Slack channels that get messages automatically, or to one you name. Fails if Slack isn’t set up for the project. If it times out, check the channel before you retry, or the message may be posted twice.
NAMETYPEREQUIREDDESCRIPTION
messagetextThe message. Can include {key} placeholders and @name mentions.
--channelchannel id—Sends to this channel instead. Always give it a value: a bare --channel isn’t refused and is sent as the channel id true.
--valuesJSON object—Values for the placeholders.
--prnumber—Pull request whose reviewers this notifies. The post is saved for devflow mr notify-status, and a channel already notified for it gets a ping in the earlier message’s thread.
Example:
devflow slack notify "Review fixes ready on {pr}" --values '{"pr":"#42"}'
Reviewer notify status
devflow mr notify-status
For each reviewer channel the panel’s Notify button shows, says whether reviewers were already notified, with the message link, and whether the next step is a send or a ping. Its source says who posted: manual (panel), auto (auto-send), gateway (devflow slack notify --pr) or slack (found only in Slack history). Follow up with devflow slack notify --pr. Read-only.
NAMETYPEREQUIREDDESCRIPTION
prIdnumberPull request number.
Example:
devflow mr notify-status 42
List Slack channels
devflow slack channels
Lists the project’s Slack channels: id, name, label, which PR labels they’re for, and whether devflow slack notify sends to them automatically. Returns no templates or tokens. Read-only.
Example:
devflow slack channels --project ABC

11Utilities

These run no action, so routing flags don’t change them.
List actions
devflow list-actions
Lists the actions DevFlow Desktop offers, by their internal names, e.g. createBranch.
Example:
devflow list-actions
List profiles
devflow list-profiles
Lists the connected Chrome profiles and the Jira projects each one owns.
Example:
devflow list-profiles
Where
devflow where
Shows the project, issue, repository and profile for the current folder, where each one came from, and whether that Chrome profile is connected. It also lists close matches and warnings. It never runs an action and always exits with 0, even when DevFlow Desktop isn’t running.
NAMETYPEREQUIREDDESCRIPTION
--jsonflag—Prints the result as JSON.
Example:
devflow where --json

12Exit codes and errors

Errors print to stderr as error [CODE]: message, with a hint line when you should check before retrying.
CODEWHENEXIT
SuccessThe command worked. --help and devflow where always end here.0
UsageErrorBad or missing arguments, nothing to route to, two projects match, or a destructive command without --force.1
ConfigErrorThe token file is missing or empty. Start DevFlow Desktop once.1
ECONNREFUSEDDevFlow Desktop isn’t running.1
NO_PROFILEThe Chrome profile that owns the project isn’t connected. Open it in Chrome.1
AMBIGUOUS_PROFILESeveral profiles or repositories match. Pass --project, --repo or --profile.1
DESTRUCTIVE_BLOCKEDDevFlow Desktop refused a destructive action that wasn’t confirmed.1
TIMEOUTNo result in time. The error says whether DevFlow picked the action up — if it did, it may still finish.1
HANDLER_FAILEDThe extension or your Git provider refused; the message has the reason.1
Unknown commands and no command at all also exit with 1. With --json, results print as ok true with the result, and errors as ok false with the code, message and hint.

13Good to know

Twelve actions aren’t safe to retry blindly
branch create, branch delete, commit template, mr create, mr close, mr merge, mr fix-comments, mr reply-fixed, the three pipeline retry forms and slack notify. If one times out after DevFlow picked it up, check first — e.g. with devflow mr find.
Five commands are destructive
branch delete, mr close, mr merge, mr fix-comments (its AI run commits and pushes), and commit template when it pushes. The CLI checks for --force before sending, and DevFlow Desktop checks again.
Warnings don’t fail the command
Things like a replaced branch name or an empty template value print to stderr as warning lines, even with --json.