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)").
project Inspect and manage the projects known to the ~/.forge-fleet registry.
remove Tear down an environment: stop the container, delete the worktree and (if ffleet created it) the branch.
status Show the live status of an environment (container, agent and blocked 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/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:
--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.
--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 Claude Code subagent to launch (e.g. code-reviewer); Claude-only. 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 Assume yes: skip the image-freshness pull prompt (warn only, never pull).
ffleet remove
Tear down an environment: stop the container, delete the worktree and (if ffleet created it) the branch.
Usage:
ffleet remove [SLUG] [flags]
Flags:
-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 tail
Print the last lines of an agent's transcript for an environment.
Usage:
ffleet tail [SLUG] [flags]
Flags:
-h, --help help for tail
--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).
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, agent and blocked state).
Usage:
ffleet status [SLUG] [flags]
Flags:
-h, --help help for status
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 project
Inspect and manage the projects known to the ~/.forge-fleet registry.
Usage:
ffleet project [command]
Available Commands:
ls List all projects known to the ~/.forge-fleet/registry.json cache.
prune Remove stale registry entries and delete their ~/.forge-fleet home dirs.
rm Permanently delete a project's ~/.forge-fleet/{id} directory and registry entry.
Flags:
-h, --help help for project
Use "ffleet project [command] --help" for more information about a command.
ffleet project ls
List all projects known to the ~/.forge-fleet/registry.json cache.
Usage:
ffleet project ls [flags]
Flags:
-h, --help help for ls
--json Emit machine-readable JSON.
ffleet project prune
Remove stale registry entries and delete their ~/.forge-fleet home dirs.
Usage:
ffleet project prune [flags]
Flags:
-h, --help help for prune
-y, --yes Skip the confirmation prompt.
ffleet project rm
Permanently delete a project's ~/.forge-fleet/{id} directory and registry entry.
Usage:
ffleet project 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