Command reference
The complete command index, generated from ffleet --help. For task-oriented
guidance see the how-to guides; for the ffleet.toml
settings see config reference.
ffleet
Forge Fleet — spin up isolated, containerized coding-agent environments.
Usage:
ffleet [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
goto Open a shell in an environment's worktree. Leave it with `exit`.
help Help about any command
init Set up ffleet.toml for the current project (home-based by default, specs/017).
ls List all environments for the project (add --json for machine-readable output).
path Print the worktree/working directory path for an environment (for cd "$(ffleet path)").
projects Act on every registered project: the whole-machine view and the machine-wide verbs.
remove Tear down an environment: stop the container, delete the worktree and (if ffleet created it) the branch.
restore Bring back every environment that should be running (after a host or Docker restart).
status Show the live status of an environment (container, runtime and agent state).
stop Stop an environment's container, keeping the worktree, branch and metadata.
tail Print the last lines of an agent's transcript for an environment.
up Start or resume an environment. State — not flags — decides what happens.
version Print the ffleet version and build metadata
Flags:
-h, --help help for ffleet
-v, --version version for ffleet
Use "ffleet [command] --help" for more information about a command.
ffleet up
Start or resume an environment. State — not flags — decides what happens.
Absent env -> create it; a live session -> attach; a stopped container or dead
agent -> rebuild from the current config and resume. On that rebuild, config-
derived settings (image, mounts, hosts, env-file, auth, dirs, agent cmd/model/reasoning/args)
refresh from the current config and are saved back; identity/continuity settings
(branch, worktree, mode, git-mode, agent, session) stay fixed at create.
Your shell's directory is never changed — use 'ffleet goto' to enter a worktree.
Usage:
ffleet up [SLUG] [flags]
Flags:
--attach Attach to the agent session afterwards, overriding the 'attach' config key.
--claude-auth string Claude credential source: auto, keychain, token, api-key, credentials-file, or external. (default "auto")
--claude-dir string Host ~/.claude dir to mount for credentials/config. (default "~/.claude")
--codex-dir string Host ~/.codex dir to mount for credentials/config. (default "~/.codex")
--coding-agent string Coding assistant to launch inside the container (e.g. claude, codex). (default "claude")
--copy-files string Gitignored files to snapshot from the main repo into a new worktree, comma-separated relative paths.
--docker-env-file string Env file passed to the container (docker --env-file).
--docker-host-bind Mount the host Docker socket so the agent can drive the host's Docker daemon (Docker-outside-of-Docker).
--extra-hosts string Extra host mappings passed to docker --add-host, comma-separated 'host:address'.
--extra-mounts string Additional docker mounts, comma-separated 'host:container[:ro|:rw]'.
--from string Base a first-time worktree on an existing branch (ignored once the env exists).
--git-local-main Base the worktree on the local main branch instead of the remote.
--git-mode string How git is set up in the container: auto, worktree, clone, or off. (default "auto")
-h, --help help for up
--here In-place mode: start/revive an agent over the current directory (no worktree).
--image string Docker image to run the agent in. (default "ghcr.io/grzegorz-aniol/forge-fleet-python:latest")
--no-attach Do not attach to the agent session afterwards, overriding the 'attach' config key.
--peek Strict, side-effect-free peek: attach only if the agent is live, never relaunch.
-p, --prompt string Message: seeds a fresh session, otherwise sent to the live/revived one.
--prompt-file string Read the prompt from a file instead of --prompt.
--subagent string Custom agent to launch (e.g. code-reviewer): a deterministic --agent flag on Claude, a best-effort delegation instruction on Codex (create-only; see docs). Overrides a template's configured subagent.
-t, --template string Seed a fresh env from a templates.<id> table in ffleet.toml; SLUG is the template ref.
--uv-cache-dir string Host uv cache dir to mount for faster installs. (default "~/.cache/uv")
--wait-timeout int Seconds to wait for the container/agent to become ready. (default 300)
-y, --yes Unattended: skip the image-freshness pull prompt (warn only, never pull) and do not attach unless --attach is given.
ffleet remove
Tear down an environment: stop the container, delete the worktree and
(if ffleet created it) the branch.
With --done it sweeps instead of removing one: it refreshes the remote refs,
then offers a multiselect of every environment whose branch has a merged pull
request and no open one. Ticking an entry is the approval — there is no second
prompt. An environment with unsaved work is listed with its reason but never
pre-ticked. The pull-request lookup needs the 'gh' CLI and a 'pm = "github"'
project; without either, nothing is offered and plain 'remove' still works.
Usage:
ffleet remove [SLUG] [flags]
Aliases:
remove, rm
Flags:
--done Sweep landed environments: pick from the ones whose pull request merged and remove them in one pass.
-h, --help help for remove
-y, --yes Skip the confirmation prompt.
ffleet stop
Stop an environment's container, keeping the worktree, branch and metadata.
Usage:
ffleet stop [SLUG] [flags]
Flags:
-h, --help help for stop
ffleet restore
Bring back every environment that should be running.
A host reboot or a Docker daemon restart destroys the containers while the
worktrees, branches and session metadata survive. 'restore' revives each
environment whose last recorded intent was 'running' and whose container is
gone; environments you parked with 'ffleet stop' are left alone.
No message is sent and nothing is attached — the agents come back idle.
'ffleet projects restore' does the same for every registered project.
Usage:
ffleet restore [flags]
Flags:
-h, --help help for restore
ffleet tail
Print the last lines of an agent's transcript for an environment.
Usage:
ffleet tail [SLUG] [flags]
Flags:
-h, --help help for tail
-n, --lines int Number of trailing transcript lines to print. (default 100)
ffleet ls
List all environments for the project (add --json for machine-readable output).
The PR column shows what the pull requests whose head branch is the
environment's branch say about it: 'merged #4', 'merged #4,#7', 'open #9',
or '—' when nothing is known. It needs the 'gh' CLI and a 'pm = "github"'
project; 'gh' handles its own auth ('gh auth login') and is optional —
without it the column simply reads '—'.
Usage:
ffleet ls [flags]
Flags:
-h, --help help for ls
--json Emit machine-readable JSON.
ffleet status
Show the live status of an environment (container, runtime and agent state).
Usage:
ffleet status [SLUG] [flags]
Flags:
-h, --help help for status
--json Emit machine-readable JSON.
ffleet path
Print the worktree/working directory path for an environment (for cd "$(ffleet path)").
Usage:
ffleet path [SLUG] [flags]
Flags:
-h, --help help for path
ffleet goto
Open a shell in an environment's worktree. Leave it with `exit`.
Usage:
ffleet goto [SLUG] [flags]
Flags:
-h, --help help for goto
ffleet init
Set up ffleet.toml for the current project (home-based by default, specs/017).
Usage:
ffleet init [flags]
Flags:
-h, --help help for init
--location string 'home' or 'local'; skips the prompt.
--project string Explicit project id override.
--worktree-root string Override the proposed worktree root.
-y, --yes Accept defaults without prompting.
ffleet projects
Act on every registered project: the whole-machine view and the machine-wide verbs.
Usage:
ffleet projects [flags]
ffleet projects [command]
Available Commands:
ls List every registered project with its environments grouped under it.
prune Remove stale registry entries and delete their ~/.forge-fleet home dirs.
restore Restore every registered project's environments (machine-wide 'ffleet restore').
rm Permanently delete a project's ~/.forge-fleet/{id} directory and registry entry.
stop Stop every environment in every registered project, keeping worktrees and metadata.
Flags:
-h, --help help for projects
--json Emit machine-readable JSON.
Use "ffleet projects [command] --help" for more information about a command.
ffleet projects ls
List every registered project with its environments grouped under it.
This is the whole-machine picture: one header per registered project — its
name, its registry id (the argument 'projects rm' takes) and its source
directory — then that project's environment table. A project the registry
cannot resolve (a stale entry, a missing ffleet.toml) is listed with the
reason instead of a table.
The PR column is blank here: pull requests are looked up in the project you
are standing in, so run 'ffleet ls' inside a project to see them.
Usage:
ffleet projects ls [flags]
Flags:
-h, --help help for ls
--json Emit machine-readable JSON.
ffleet projects restore
Bring back every environment that should be running, in every registered
project.
Same contract as 'ffleet restore', widened: each environment whose last
recorded intent was 'running' and whose container is gone is revived, and
the ones you parked with 'ffleet stop' are left alone. Projects come from
the registry, so this works from any directory.
Usage:
ffleet projects restore [flags]
Flags:
-h, --help help for restore
ffleet projects stop
Park the fleet: stop every environment's container across every registered
project, keeping the worktrees, branches and session metadata.
Same contract as 'ffleet stop SLUG', widened: each environment is recorded
as parked, so a later 'ffleet projects restore' leaves it down. Bring one
back with 'ffleet up SLUG'.
Usage:
ffleet projects stop [flags]
Flags:
-h, --help help for stop
ffleet projects prune
Remove stale registry entries and delete their ~/.forge-fleet home dirs.
Usage:
ffleet projects prune [flags]
Flags:
-h, --help help for prune
-y, --yes Skip the confirmation prompt.
ffleet projects rm
Permanently delete a project's ~/.forge-fleet/{id} directory and registry entry.
Usage:
ffleet projects rm PROJECT_ID [flags]
Flags:
-h, --help help for rm
-y, --yes Skip the confirmation prompt.
ffleet version
Print the ffleet version and build metadata
Usage:
ffleet version [flags]
Flags:
-h, --help help for version