flowforge run
flowforge run is the binary equivalent of dispatching a slash command from inside Claude Code. It locates the project root, resolves the command identifier to a markdown file under commands/flowforge/, extracts the bash blocks from that file, and executes them in a child shell. The entire FlowForge slash-command catalog is available through this single subcommand.
Synopsis
Section titled “Synopsis”flowforge run <command> [args...]<command> is required. Additional positional arguments are forwarded to the command body as a space-joined value of the ARGUMENTS environment variable.
Description
Section titled “Description”flowforge run replaces the legacy run_ff_command.sh helper. It walks up from the current directory to find the FlowForge project root, identified by either a .flowforge/ directory or a commands/flowforge/ directory. From that root it converts the colon-separated command id to a relative path under commands/ and reads the corresponding markdown file:
| Command id | Resolved path |
|---|---|
flowforge:session:start | commands/flowforge/session/start.md |
flowforge:dev:status | commands/flowforge/dev/status.md |
flowforge:help | commands/flowforge/help.md |
In FlowForge’s own repository every command lives under commands/flowforge/, so the flowforge:-qualified form is what actually resolves. Other projects that consume FlowForge may install commands under different top-level namespaces.
Inside the markdown file, the binary scans for fenced code blocks beginning with the literal line ```bash and ending with ```. Every line strictly between those fences is concatenated into a single bash script; everything else (prose, headings, non-bash code blocks) is ignored. Execution is performed by spawning bash -c <script> with the project root as the working directory and os.Stdin, os.Stdout, and os.Stderr wired through. The full parent environment is inherited and ARGUMENTS is appended.
This means slash commands written for Claude Code work unchanged from the binary, and the binary in turn is the recommended way to script FlowForge workflows from CI, makefiles, and shell aliases.
The path is sanitized before use: flowforge run ../escape is rejected because the cleaned path would not begin with the commands directory. Four legacy command forms are intercepted with a migration message: startsession and its flowforge:-qualified variant flowforge:startsession both redirect to flowforge run flowforge:session:start, and endday and flowforge:endday both redirect to flowforge run flowforge:session:end.
Arguments
Section titled “Arguments”| Position | Name | Required | Description |
|---|---|---|---|
| 1 | command | yes | Colon-separated command id (flowforge:session:start, flowforge:dev:checkrules, flowforge:agent:manage). Mapped to a markdown file relative to the project’s commands/ directory. |
| 2..N | args... | no | Trailing positional arguments. Joined with single spaces and exported as ARGUMENTS to the child bash. |
Options
Section titled “Options”None at the subcommand level. Cobra’s standard --help flag is available.
Environment variables
Section titled “Environment variables”| Variable | Direction | Purpose |
|---|---|---|
ARGUMENTS | exported to child | Space-joined trailing arguments. Slash commands typically read this with ${ARGUMENTS:-} and use it for ticket ids, options, and the ?/help argument convention. |
DEBUG | inherited | Many slash commands switch to set -x when DEBUG=1. Pass it through with DEBUG=1 flowforge run .... |
TMUX | inherited | Slash commands that delegate to tmux features check this. |
The full parent environment is inherited; the binary appends but does not strip variables.
Examples
Section titled “Examples”Start a tracked session for ticket 14:
flowforge run flowforge:session:start 14The trailing 14 becomes ARGUMENTS=14 in the child shell, which the command body reads to identify the ticket.
Show the project status:
flowforge run flowforge:dev:statusShow project status with debug tracing:
DEBUG=1 flowforge run flowforge:dev:statusCheck a single FlowForge rule rather than the full sweep:
flowforge run flowforge:dev:checkrules 3Inspect what flowforge run does by passing the help convention through:
flowforge run flowforge:session:start ?Most FlowForge commands respond to ? or help as the first argument by printing a usage block and exiting 0.
Exit codes
Section titled “Exit codes”flowforge run propagates the exit code of the child bash. If the command file cannot be located, the path is unsafe, or extraction yields no bash content, the binary exits non-zero with a descriptive error before invoking bash.
| Code | Meaning |
|---|---|
0 | The script ran to completion with status 0. |
1 | Project root not found, command file missing, path traversal attempted, or no bash code blocks present. |
| Other | Forwarded from the child bash via os.Exit(exitErr.ExitCode()). |
Related commands
Section titled “Related commands”flowforge tui— interactive controller surface for the same commands./flowforge:session:start— typical first command to run./flowforge:dev:status— status overview./flowforge:dev:checkrules— full rule sweep.- Sessions — what slash commands operate on.
flowforge worker
Section titled “flowforge worker”flowforge worker is a hidden internal subcommand invoked by the TUI controller when it spawns a new tmux window. It is not intended for direct user invocation; it is documented here for completeness even though it is hidden from flowforge --help output (Hidden: true in cmd_worker.go).
flowforge workerThe worker validates the TMUX environment variable, prints FlowForge worker ready to stdout, and exits. Future versions implement the full worker event loop. Running flowforge worker outside tmux fails with not inside a tmux session (TMUX env var is not set). There are no flags or arguments. End-users should always go through flowforge tui.