commands

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         Bind container ports to the host network.
      --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.
      --project-name string      Project this environment belongs to; namespaces its worktree and container.
  -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.
      --source-dir string        Path to the source git repository to create the worktree from.
  -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)
      --worktree-root string     Directory under which per-environment worktrees are created.

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
      --project-name string    Project this environment belongs to; namespaces its worktree and container.
      --source-dir string      Path to the source git repository to create the worktree from.
      --worktree-root string   Directory under which per-environment worktrees are created.
  -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
      --project-name string    Project this environment belongs to; namespaces its worktree and container.
      --worktree-root string   Directory under which per-environment worktrees are created.

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)
      --project-name string    Project this environment belongs to; namespaces its worktree and container.
      --worktree-root string   Directory under which per-environment worktrees are created.

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.
      --project-name string    Project this environment belongs to; namespaces its worktree and container.
      --worktree-root string   Directory under which per-environment worktrees are created.

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
      --project-name string    Project this environment belongs to; namespaces its worktree and container.
      --worktree-root string   Directory under which per-environment worktrees are created.

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
      --project-name string    Project this environment belongs to; namespaces its worktree and container.
      --worktree-root string   Directory under which per-environment worktrees are created.

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
      --project-name string    Project this environment belongs to; namespaces its worktree and container.
      --worktree-root string   Directory under which per-environment worktrees are created.

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