The CLI, in depth. Then the verbs.

Why a CLI

A skill runs inside a session. It does not choose the directory the session was born in, it cannot see which binaries are on the PATH, and finding that out costs tool calls that eat the context the work needed.

The CLI runs before the session and has the environment. It answers, for free, three questions the skill would answer expensively:

1. Where am I? Which repo, which context manifest applies, where the checkouts live.
2. What exists on this machine? Which review agents are installed, whether gh is available, whether the vault exists.
3. What is missing? If a hard requirement of the verb is absent, the CLI aborts before a whole session is spent discovering that mid-work.

The answers go into the first prompt as a block of text. The skill reads the block instead of investigating.

Install

The CLI lives in cli/ inside the Flux repository and compiles to a single binary with Bun.

cd cli
bun run setup

That runs bun build --compile, re-signs the binary, and installs it to ~/.local/bin/flux. Make sure ~/.local/bin is on your PATH. Bun is needed to compile; at runtime the binary depends on neither Bun nor Node.

Why the re-signing step exists: on Macs under MDM with EndpointSecurity (JumpCloud, SentinelOne and the like), Bun's default ad-hoc signature is rejected. setup.sh runs codesign --force --sign - and then warms the binary up, because the first exec right after signing races an asynchronous scan by the security daemon and can die with exit 137 with nothing wrong with the binary. The script absorbs that race there, not the first time you actually need the command.

flux                  # interactive mode
flux resolve --json   # print the resolved context

Mental model

Three layers, and the distinction matters because error messages speak in these terms:

The CLI implements no verb. It builds the prompt that invokes the verb's skill and gets out of the way. Type the same prompt by hand inside a session and you get the same result; the CLI only spares you the discovery.

Agents live at three levels the CLI calls lenses:

The CLI discovers L2 and L3 and reports which it found. When a repo has neither, flux equip exists to create the L2.

Usage

Verbs

flux <verb> [target] [--repo <slug>] [flags]

With no arguments, flux opens an interactive mode that asks for the verb (a menu with each one's description), the target, the repo, and whether to run on another machine. It assembles the equivalent argv and follows the same path as always. It only opens when stdin is a TTY; inside a script, flux with no arguments prints the usage and exits.

flux                              # interactive
flux peek                         # glance at the current working tree
flux peek 8249                    # glance at PR #8249 of the cwd repo
flux review 8249 --repo backoffice
flux build LAB-142 --repo flux

The target is passed to the verb uninterpreted, with one exception: a Linear ticket requires --repo. A LAB-142 does not say which repo the work happens in, and the CLI refuses rather than guess.

Mechanical subcommands

Three subcommands open no session: they print JSON and exit. The skills consume them, and you use them to debug.

flux resolve --json prints the resolved context and nothing else. It is the command for "why does flux think I am in this profile?".

{
  "profile": "personal",
  "manifest_path": "/Users/you/www/personal/.claude/flux-context.json",
  "anchor": "/Users/you/www/personal/flux",
  "flux_root": "/Users/you/.claude/plugins/cache/flux/flux/1.29.1/plugins/flux",
  "flux_root_source": "env:FLUX_HOME",
  "exec_command": "workflow",
  "exec_fallback": "flux-engine-flux",
  "lenses": { "l2_paths": ["/Users/you/agents/personal/flux"], "l3_paths": [] },
  "warnings": []
}

flux preflight <verb> [target] --json runs the full check for a specific verb: hard and soft requirements, holistic reviewer, capability level. Each verb declares what it needs. A missing hard requirement aborts; a missing soft one degrades, and the CLI states what is lost.

FULL is tentative because the CLI sees the disk, not the session: it knows the agent file exists, not whether the harness registered it as invokable. The skill confirms that from inside.

flux gather pr <n|URL> --json collects a PR through gh: metadata, diff, and with --threads the review threads. Only verbs that answer threads ask for them.

Flags

--dry is the inspection tool. It prints the exact command line that would be launched, prompt included. It is how you check what the CLI discovered without spending a session.

Which harness

The CLI builds the invocation for three harnesses. Which one is resolved by a cascade, stopping at the first rung that answers:

--harness together with FLUX_CLAUDE_CMD is an error: the flag is explicit intent, and asking for both is an ambiguity the CLI will not resolve for you. FLUX_HARNESS and preferred_harness are environment defaults, so the override beats them silently. Rung 5 is not the old silent default: the banner carries harness_source: default, so the skill can tell "chose claude" from "nobody chose".

The -- before the prompt is mandatory, not style: the body starts with --- PREFLIGHT RESOLVIDO, and without the separator cursor and codex read that as an option and refuse. --safe drops the permission flag on all three. --new is only supported on claude for now; the other two warn and run in the current tab.

The banner preview. Before launching, the CLI shows the block it is about to send and opens a three-option menu: send as is, attach an extra comment, cancel. The comment is appended to the prompt; it is where you add "focus on the date parsing" without rewriting the command. --yes skips it, and it does not appear when stdin is not a TTY.

The context manifest

flux-context.json declares the context of a workspace: where the repos live, which vault to use, which Linear organization, which agents exist. It is looked up at .claude/flux-context.json or .cursor/flux-context.json, walking up the directory tree from the anchor.

{
  "name": "acme",
  "workspace_root": "~/www/acme",
  "repos": ["api-gateway", "web-monorepo", "payments"],
  "vault_root": "~/.notes",
  "vault_context": "acme",
  "linear_org": "acme-eng",
  "no_emdash": true,
  "exec_command": "workflow",
  "exec_fallback": { "payments": "acme-engine-payments", "default": "acme-implement" },
  "specialists_root": "~/agents/{repo}/repo-owner.md",
  "holistic_reviewer": "acme:reviewer"
}

Without a manifest the CLI still works. The profile becomes generico: the anchor is the cwd, the repos are the subdirectories with a .git, and nothing is persisted to a vault. What is lost is stated in the banner, not discovered halfway.

exec_fallback takes two shapes: a scalar when one command serves every repo, or a map when repos have different engines. Resolution is repo → default → none. A map that names neither this repo nor a default sends build to autonomous mode rather than borrowing another repo's engine: running code through the wrong pipeline, silently, is worse than running it through none.

How context is resolved

The anchor is the target, not the cwd

cd ~
flux build LAB-142 --repo flux

That has to find the profile of the workspace where flux lives, not your home's. So: parse the target first, without opening anything; the anchor is the checkout of --repo when given, else the cwd; the manifest is found walking up from the anchor.

When the slug does not resolve nearby, the CLI scans the known manifests for one that claims it (through the repos field, or by having <workspace_root>/<slug>/.git). One claims it: that whole profile is adopted, with a warning. More than one: it asks. None: it anchors on the cwd and warns.

slug "flux" resolved by scanning manifests (not by a nearby manifest) — check the context is right

FLUX_ROOT: where the skills live

The CLI needs the contract files (shared/*.md) to check hard requirements. In order: $FLUX_HOME if set and existing; the harness plugin variables (CLAUDE_PLUGIN_ROOT, CURSOR_PLUGIN_ROOT, CODEX_PLUGIN_ROOT); and a heuristic that scans ~/.claude* and ~/.cursor for plugins/cache/flux/flux/<version>/ and picks the highest version.

The heuristic warns, because it can pick the wrong cache when you have more than one account or config dir. If you do, set FLUX_HOME explicitly. That rung exists for exactly that.

The PREFLIGHT block

The CLI's product. It goes at the top of the prompt, and the skill reads it instead of investigating:

--- PREFLIGHT RESOLVIDO (flux-cli v1.29.1) ---
perfil: acme
manifesto: /Users/you/www/acme/.claude/flux-context.json
ancora: /Users/you/www/acme/payments
flux_root: /Users/you/.claude/plugins/cache/flux/flux/1.29.1/plugins/flux
flux_root_source: env:FLUX_HOME
exec_command: workflow
exec_fallback: acme-engine-payments
lentes:
  l2_paths: /Users/you/agents/payments
  l3_paths: ausente
harness: claude
harness_source: manifesto
flux_cmd: /flux: (session_revalidation_required)
--- FIM PREFLIGHT RESOLVIDO ---

The block is advisory, deliberately. It is a starting point, not the final truth. session_revalidation_required lists what the skill must re-check from inside the session, because it depends on state the CLI cannot see:

A CLI that asserted those four would be lying with the appearance of precision. It asserts what it measured and marks the rest.

Running remotely

flux review 8249 --repo backoffice --remote worzix
flux review 8249 --repo backoffice --remote          # asks which

Without an alias, the CLI reads the Host entries of ~/.ssh/config, tests which are reachable now, and shows only those in a menu. A machine can be opted out with a comment right above its Host block:

# flux:ignore
Host production
  HostName ...

It is for machines that sit in ~/.ssh/config for deploy convenience and where an agent harness must never run.

Two known traps. --remote builds ssh -t <host> zsh -lic 'flux ...' and does not cd: the session is born in the remote $HOME. So the manifest may not be found walking up from there, and FLUX_ROOT is resolved by the heuristic on the remote, which can hit another config dir's cache. If you use more than one account or context on the remote, wrap the call in a shell function that does an explicit cd and passes FLUX_HOME and FLUX_CLAUDE_CMD.

Environment variables

FLUX_CLAUDE_CMD and shell functions. The CLI executes through [$SHELL, "-i", "-c", ...], an interactive shell. Your .zshrc is loaded, so shell functions work as the target. It is the mechanism to route the session through a wrapper of your own: pick an account, export variables, whatever it is. The CLI does not validate an override's target, because it cannot: whoever dictated the invocation knows what it is.

Troubleshooting

The resolved profile is wrong

Run flux resolve --json and look at anchor and manifest_path. If the anchor is in the wrong place, you either forgot --repo or the manifest is not where you think. A "scanning manifests" warning means the slug was found by wide search and is worth checking.

flux_root_source: heuristica-cli

The CLI guessed where the skills live. It works, but can hit the wrong cache with more than one config dir. Set FLUX_HOME.

The binary dies with exit 137 right after install

A race with the macOS security daemon (MDM, EndpointSecurity). setup.sh already absorbs it; if it happens outside, wait a few seconds and run again.

<binary> not found on PATH

The resolved harness is not on the PATH. The check uses /usr/bin/which, which only sees binaries; a shell function does not appear there even though it works at execution, which uses an interactive shell. If your claude is a function, point at it with FLUX_CLAUDE_CMD: the guard is skipped when the invocation comes from an override, because the CLI cannot validate a target you dictated. For cursor, the guard checks the cursor binary, not the agent subcommand; probing it live would cost seconds per call, so that stays a known limitation.

The verbs: the cycle

Everything above is what the CLI does before a verb runs. This is what the verbs do. The family is a cycle, and each verb hands off to the next:

Two verbs sit outside the cycle and prepare the ground (map, equip); two are optional detours (refine, probe). Every verb opens its output with a profile banner declaring which lenses it found and what degraded, so a reduced run can never pass for a full one.

Setup verbs setup

Two verbs sit outside the cycle. They are what you do to a machine or a repo so that the cycle can run with every lens and without falling into autonomous mode.

Optional verbs optional

Two detours before flux:issue. Neither is required: whoever does not need to refine or investigate goes straight to the issue.