CLI reference

A complete, generated reference for every af command and flag, produced from the Cobra command tree. This page is regenerated by scripts/gen-docs.sh and verified in CI, so it never drifts from the binary — do not edit it by hand.

Run af <command> --help for the same information at the terminal. For a narrative, task-oriented tour of the CLI see the CLI guide.

Commands

• af — Agent Factory - Manage multiple AI agents like Claude Code, Aider, Codex, Gemini, and Amp.
• af accounts — Manage per-session agent credential directories
• af accounts add — Register a credential directory for an agent account
• af accounts list — List registered agent accounts
• af accounts login — Log in to an agent account by running the agent's own login flow
• af agent-server — Run a headless single-workspace backend (not the web UI — that is 'af daemon')
• af api — Show the daemon-hosted HTTP/JSON API catalog
• af bug-report — Bundle logs, versions, tasks, and redacted state for a bug report
• af completion — Generate the autocompletion script for the specified shell
• af completion bash — Generate the autocompletion script for bash
• af completion fish — Generate the autocompletion script for fish
• af completion powershell — Generate the autocompletion script for powershell
• af completion zsh — Generate the autocompletion script for zsh
• af config — Read global or project-effective config and write global config
• af config get — Print one global or project-effective config value
• af config list — Print global or project-effective config values
• af config migrate — Rewrite deprecated config keys to their current spelling
• af config set — Set one global config key
• af config unset — Clear a config override or migrated global setting
• af config validate — Check that the global config parses and validates
• af daemon — Manage the background daemon: serves the web UI and schedules tasks
• af daemon adopt — Hand a detached daemon back to the installed autostart unit
• af daemon install — Register the daemon to start automatically at login
• af daemon restart — Restart the running daemon without stopping live sessions
• af daemon status — Report daemon liveness, config freshness, and supervision
• af daemon uninstall — Remove the daemon autostart unit
• af debug — Print debug information like config paths
• af doctor — Diagnose setup, daemon health, and leaked session resources
• af keys — Show the effective TUI key bindings (defaults plus [keys] rebinds)
• af projects — Manage projects and durable registrations
• af projects add — Add a project: register a repo by path with a stable local identity
• af projects delete — Delete a project, archiving its restorable sessions
• af projects list — List registered projects
• af projects rebind — Rebind a registered project after its checkout moves
• af quota — Show usage-limit status for each agent CLI
• af reset — Factory-reset Agent Factory: remove AF sessions, tasks, project registrations, worktrees, and state (keeps repos and config)
• af sessions — Manage sessions
• af sessions archive — Finish with a session by archiving it for later restore
• af sessions attach — Attach to a session's terminal
• af sessions backends — List the runtimes this project can create sessions on
• af sessions create — Create a new session
• af sessions get — Get a session by title
• af sessions handoff — Continue a session under a different agent, in place
• af sessions kill — Permanently delete a session and af-owned resources
• af sessions list — List sessions in the current project
• af sessions preview — Preview a session's terminal content
• af sessions restore — Restore an archived, lost, or dead session
• af sessions retry-limit — Retry a usage-limit resume or inspected handoff
• af sessions send-prompt — Send a prompt to a session (or broadcast to all with --all)
• af sessions tab-create — Spawn a shell, process, web, or VS Code tab in a session
• af sessions tab-delete — Delete a single tab from a session
• af sessions tab-rename — Rename a tab of a session
• af sessions tab-reorder — Move a tab within a session's tab order
• af sessions tabs — Manage a session's tabs (create/delete/rename/reorder)
• af sessions tabs create — Spawn a shell, process, web, or VS Code tab in a session
• af sessions tabs delete — Delete a single tab from a session
• af sessions tabs rename — Rename a tab of a session
• af sessions tabs reorder — Move a tab within a session's tab order
• af sessions watch — Wait for idle, or a fleet stop-state change or disappearance
• af sessions whoami — Identify the current Agent Factory session
• af tasks — Manage tasks
• af tasks add — Add a new task bound to the current project
• af tasks get — Get a task in the current project by ID
• af tasks list — List tasks in the current project
• af tasks remove — Remove a task in the current project
• af tasks restart — Restart an enabled watch task without process overlap
• af tasks show — Show one task's schedule health and audit trail
• af tasks trigger — Trigger a task in the current project to run immediately
• af tasks update — Update a task in the current project
• af token — Manage the daemon's bearer token for the direct-TCP API
• af token rotate — Replace the bearer token with a fresh one and print it
• af token show — Print the bearer token (generating it if absent)
• af upgrade — Upgrade agent-factory to the latest release on the configured channel
• af version — Print the version number of agent-factory

af

Agent Factory - Manage multiple AI agents like Claude Code, Aider, Codex, Gemini, and Amp.

Run 'af' with no arguments to open the TUI. The subcommands below drive the same daemon non-interactively (af sessions, af tasks emit JSON).

The daemon also serves the web UI — the same sessions in a browser — at http://localhost:8443, which needs no token by default. See 'af daemon --help' for the web UI, the listener and its auth, and autostart; to drive a daemon on another machine, start with the remote guide: https://sachiniyer.github.io/agent-factory/remote-http-auth/

af [flags]

Subcommands

• af accounts — Manage per-session agent credential directories
• af agent-server — Run a headless single-workspace backend (not the web UI — that is 'af daemon')
• af api — Show the daemon-hosted HTTP/JSON API catalog
• af bug-report — Bundle logs, versions, tasks, and redacted state for a bug report
• af completion — Generate the autocompletion script for the specified shell
• af config — Read global or project-effective config and write global config
• af daemon — Manage the background daemon: serves the web UI and schedules tasks
• af debug — Print debug information like config paths
• af doctor — Diagnose setup, daemon health, and leaked session resources
• af keys — Show the effective TUI key bindings (defaults plus [keys] rebinds)
• af projects — Manage projects and durable registrations
• af quota — Show usage-limit status for each agent CLI
• af reset — Factory-reset Agent Factory: remove AF sessions, tasks, project registrations, worktrees, and state (keeps repos and config)
• af sessions — Manage sessions
• af tasks — Manage tasks
• af token — Manage the daemon's bearer token for the direct-TCP API
• af upgrade — Upgrade agent-factory to the latest release on the configured channel
• af version — Print the version number of agent-factory

Flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
-p, --program	string	Program to run in new sessions (one of: claude, codex, aider, gemini, amp, opencode, devin)
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.
-v, --version		version for af

af accounts

Manage per-session agent credential directories

Prepare the credential directories a session can later be scoped to.

An account is one of an agent's logged-in identities, held as a directory the agent CLI treats as its home. af never reads, stores, or forwards the credential itself — it decides which directory a session sees, and the agent's own login flow puts the material there.

add creates that directory and prints its path · login runs the agent's own login flow against it · list shows what is registered.

af accounts login codex work

That one command registers the account if needed, starts codex's own login in a tmux session scoped to it, hands you the terminal for the device-code step, and afterwards reports whether the account holds a credential — read from the agent's own credential file, by checking that it exists.

Every login af runs is browser-free. The pane is on the daemon's host, which is usually headless and remote, so the flow that fits is the device code: the CLI prints a URL and a code, you sign in from whatever device you are holding, and the CLI polls. af selects it per agent — see af accounts login --help.

You can still do it by hand, and af runs exactly these:

CODEX_HOME=$(af accounts add codex work) codex login --device-auth CLAUDE_CONFIG_DIR=$(af accounts add claude work) BROWSER=true claude auth login GEMINI_CLI_HOME=$(af accounts add gemini work) NO_BROWSER=true gemini

Those variables do not all have the same shape, and mixing them up is the easy mistake. CODEX_HOME and CLAUDE_CONFIG_DIR name the config directory itself. GEMINI_CLI_HOME is a HOME-like root: gemini appends .gemini/ to it, so the account directory af prints holds the credential at

/.gemini/oauth_creds.json or /.gemini/gemini-credentials.json. Point the variable at the printed directory, never at a .gemini path inside it.

Select an account for a session with:

af sessions create --account work

That both injects the account's directory and removes every other identity-bearing variable for the agent. The removal is what makes the selection real: an ambient ANTHROPIC_API_KEY or OPENAI_API_KEY outranks the config directory, so without it a session would authenticate as whoever that key belongs to while every visible signal reported the selected account.

Account-scoped sessions require the local or docker backend, and tmux 3.2 or newer. af refuses rather than falling back, because a fallback would run on the ambient account while reporting the one you asked for.

ssh, sandbox and hook refuse by design, not because the work is pending. docker bind-MOUNTS the directory, so account writes land in your real account. An account is a writable agent home, so the agent writes refreshed authentication back into it. For ssh, sandbox and hook, af cannot establish that those writes come back, so a rotated token can be lost. If your provider rotates refresh tokens, losing it also invalidates the copy on this machine — so a feature meant to NARROW where an identity is used could break it.

By default af never switches accounts on its own. With limit_auto_resume enabled, an explicit limit_account_candidates list may opt an unpinned local session into switching after a usage limit. af skips registered candidates with a current limit observation, says which identity changed in the session, and waits normally when none is usable. Docker account-scoped creates remain supported, but automatic Docker replacement is disabled until af can durably identify and reap a crash-surviving container and freeze its complete provision plan. An explicit --account is a pin that automatic switching never overrides.

af accounts

Subcommands

• af accounts add — Register a credential directory for an agent account
• af accounts list — List registered agent accounts
• af accounts login — Log in to an agent account by running the agent's own login flow

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af accounts add

Register a credential directory for an agent account

Create the credential directory for an account and print its path.

This makes a place; it does not log in. Run the agent's own login flow against the printed directory to put credentials there.

Registration is idempotent — running it again on an existing account reports the same directory and preserves existing settings. Missing non-credential runtime settings may be seeded; notices explaining them are printed to stderr.

af accounts add <agent> <name> [flags]

Flags

Flag	Type	Description
--json		Output the {data,error} JSON envelope

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af accounts list

List registered agent accounts

List the registered accounts, for one agent or for every agent that supports account scoping.

An agent absent from this list is one whose credential relocation af has not verified, not one that is merely unconfigured — af reports unsupported rather than accepting a selection that would silently do nothing.

af accounts list [agent] [flags]

Flags

Flag	Type	Description
--json		Output the {data,error} JSON envelope

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af accounts login

Log in to an agent account by running the agent's own login flow

Run the agent's own login command against an account's credential directory.

af registers the account if it does not exist yet, asks the daemon to start the agent's login flow in a tmux session scoped to that account, and hands you the terminal so you can complete the device-code step. When the flow ends, af reports whether the account holds a credential — read from the agent's own credential file, by checking that it exists, never by reading it.

af accounts login codex work af accounts login claude personal

af never reads, stores, or forwards the credential. It sets one variable and runs the agent's own flow:

claude → claude auth login · codex → codex login --device-auth · gemini → gemini

The login is browser-free. The pane runs on the daemon's host, which is usually headless and remote, so a browser-callback sign-in there opens a browser nobody is sitting in front of, or waits for a redirect to that host's own localhost that your machine cannot reach. Every flow above prints a URL and waits for a code you paste back, and af selects that path per agent:

codex codex login --device-auth prints a verification URL and a device code gemini the pane sets NO_BROWSER=true · gemini prints the URL and prompts "Enter the authorization code: " claude claude has no such flag, so the pane sets BROWSER=true — a no-op opener the CLI honours — and claude prints "If the browser didn't open, visit:" with the URL, then "Paste code here if prompted > "

Sign in on whatever device you are actually holding, then paste the code into the pane.

The login pane gets exactly the environment an account-scoped session gets: the account's directory injected, and every other identity-bearing variable for that agent REMOVED. The removal is what makes the login land in the account you asked for — an ambient ANTHROPIC_API_KEY or OPENAI_API_KEY outranks the config directory, so without it the CLI could report success against that key's identity while the account directory stayed empty.

It removes identity, not environment: proxies, private CA roots and your git and SSH configuration are passed through as always. If the login needs something else — DISPLAY or BROWSER, on a host with a browser to open — add it to session_env_passthrough. Naming BROWSER or NO_BROWSER there also overrides the browser-free defaults above; your value wins.

The flow runs on the daemon's host, where the credential directory is. With --no-attach af prints the tmux session to attach to instead of taking your terminal.

af accounts login <agent> <name> [flags]

Flags

Flag	Type	Description
--json		Output the {data,error} JSON envelope
--no-attach		Start the login flow and print how to attach instead of taking this terminal

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af agent-server

Run a headless single-workspace backend (not the web UI — that is 'af daemon')

Run a headless agent-server for exactly one session's workspace, served over the same REST + WebSocket protocol the daemon speaks, behind a plain-HTTP listener that requires a bearer token on every request.

This does not start the web UI, and serves no frontend at all — opening its port in a browser returns a 404 saying so. If you want the browser app, run the daemon — any 'af' command starts it — and open http://localhost:8443. The web UI is bundled into the daemon and served from its network.listen_addr; agent-server is only the headless per-workspace backend that a daemon drives, and it exists to be consumed by a daemon rather than opened by a person.

This is the process that runs inside a docker container or on an ssh remote (#1592 Phase 4): a remote daemon dials the authed URL it exposes and drives the workspace exactly as it drives a local in-process session. Run it directly only to host one workspace as a backend for a daemon on another machine.

The listener always requires the token and serves plain HTTP (no TLS) — reach it over a private network or a tunnel (the docker/ssh runtimes forward a loopback port). Its token is mandatory for every peer, whatever the global network.require_token key says: that key governs only the daemon's own web listener. On startup it prints one JSON line to stdout carrying the bound address and the bearer token. On SIGINT/SIGTERM it tears the workspace down (kills tmux, removes the worktree) — durability of in-progress work is the driving daemon's job (push the branch before shutdown), not this server's.

af agent-server [flags]

Flags

Flag	Type	Description
--listen	string	HTTP TCP bind address (host:port); :0 lets the kernel pick a free port (default 127.0.0.1:0)
--program	string	Agent program to run (default: the configured default_program)
--program-resolved		Treat --program as an already-resolved runtime command
--repo	string	Repository path the workspace runs against (default: current directory)
--session-env	stringSlice	Additional exact environment variable name an agent may inherit (repeatable)
--title	string	Session title for the workspace (required)

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af api

Show the daemon-hosted HTTP/JSON API catalog

Print the HTTP/JSON API the daemon exposes over a local Unix socket.

The daemon serves a small JSON API — a 1:1 mirror of the session and task operations the CLI performs — on a 0600 Unix socket (owner-only; there is no TCP port and no token). This command lists the resolved socket path and every endpoint with a ready-to-run curl example.

It is read-only and never contacts or starts the daemon; it just prints the catalog. Use --json for a machine-readable form wrapped in the shared {data,error} envelope. Full reference: docs/http-api.md.

af api [flags]

Flags

Flag	Type	Description
--json		Emit the catalog as JSON wrapped in the {data,error} envelope

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af bug-report

Bundle logs, versions, tasks, and redacted state for a bug report

Collect a single, shareable diagnostics bundle for triage:

• the daemon log tail (bounded to the last ~2MiB / 5000 lines)
• versions: af, Go, OS/arch, and the daemon's version snapshot
• the configured tasks (redacted)
• the session state from instances.json (redacted)
• the daemon health snapshot (same no-spawn probe as af daemon status)
• the global config file, if any (redacted)

By default the redacted bundle is written to a single text file (~/af-bug-report-.txt) and a pre-filled GitHub issue DRAFT is opened in your browser. The draft ALWAYS targets the agent-factory project (github.com/sachiniyer/agent-factory) — never whatever repo you happen to be in — because it reports a bug in af itself.

The draft body carries a bounded, redacted summary of the key diagnostics (versions, daemon status, counts, and the newest log lines) so the report is useful even as filed; the complete bundle is too large for a URL, so it stays on disk for you to attach. The draft is never submitted for you: review it, drag the bundle file onto the issue, and click Submit yourself. If neither gh nor a browser opener is available, the command falls back to just writing the bundle file and printing where it is so you can attach it to an issue by hand.

Use -o/--output or --file to skip GitHub and only write the bundle file.

REDACTION IS BEST-EFFORT. Free-text and secret-bearing fields (session titles, session prompts, task prompts, tab and session commands, tab names, account labels, remote metadata) are dropped. A registered account label is replaced by the same marker everywhere it appears — the session records, and the daemon log and config sections that name it as text — so the report is no less private through its log than through its records; if the accounts registry cannot be read, the bundle says so in its collection errors instead of looking redacted when it is not. Every directory the bundle names is replaced by the role it plays ([repo:N], [worktree:N], [af-home], ~) rather than by its own name, and your username by [user]; and known credential shapes are scrubbed wherever they appear. Perfect redaction is impossible — open the file and review it before sharing it publicly.

Use --json to emit the structured manifest (wrapped in the shared {data,error} envelope) to stdout instead of writing a file or opening a draft.

af bug-report [flags]

Flags

Flag	Type	Description
--file		Only write the bundle file (to ~/af-bug-report-.txt); do not open a GitHub issue draft
--json		Emit the structured manifest to stdout (in the {data,error} envelope) instead of writing a file or opening a draft
-o, --output	string	Write the bundle to this path and skip opening a GitHub draft (implies --file)

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af completion

Generate the autocompletion script for the specified shell

Generate the autocompletion script for af for the specified shell. See each sub-command's help for details on how to use the generated script.

af completion

Subcommands

• af completion bash — Generate the autocompletion script for bash
• af completion fish — Generate the autocompletion script for fish
• af completion powershell — Generate the autocompletion script for powershell
• af completion zsh — Generate the autocompletion script for zsh

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af completion bash

Generate the autocompletion script for bash

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(af completion bash)

To load completions for every new session, execute once:

Linux:

af completion bash > /etc/bash_completion.d/af

macOS:

af completion bash > $(brew --prefix)/etc/bash_completion.d/af

You will need to start a new shell for this setup to take effect.

af completion bash

Flags

Flag	Type	Description
--no-descriptions		disable completion descriptions

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af completion fish

Generate the autocompletion script for fish

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

af completion fish | source

To load completions for every new session, execute once:

af completion fish > ~/.config/fish/completions/af.fish

You will need to start a new shell for this setup to take effect.

af completion fish [flags]

Flags

Flag	Type	Description
--no-descriptions		disable completion descriptions

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af completion powershell

Generate the autocompletion script for powershell

Generate the autocompletion script for powershell.

To load completions in your current shell session:

af completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

af completion powershell [flags]

Flags

Flag	Type	Description
--no-descriptions		disable completion descriptions

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af completion zsh

Generate the autocompletion script for zsh

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(af completion zsh)

To load completions for every new session, execute once:

Linux:

af completion zsh > "${fpath[1]}/_af"

macOS:

af completion zsh > $(brew --prefix)/share/zsh/site-functions/_af

You will need to start a new shell for this setup to take effect.

af completion zsh [flags]

Flags

Flag	Type	Description
--no-descriptions		disable completion descriptions

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af config

Read global or project-effective config and write global config

Read and write keys in the global config (~/.agent-factory/config.toml).

"get"/"list" print the effective config for the current repository, including its checked-in and personal per-project layers. Pass --repo to inspect another project. Outside a git repository they fall back to global defaults. --explain shows every candidate and why it did or did not supply the effective value.

"set"/"unset" write config in place so all comments and ordering are preserved. Without --project, set changes one settable global key and unset clears one migrated grouped/flat alias pair. With --project they edit that registered project's machine-local override instead (built-in < global < in-repo < personal project), which is never checked into the repository. "af config set" applies a change to a running daemon in place where the key allows it (#2480), so most take effect without a restart; a raw hand-edit of config.toml still applies on the next start.

af config

Subcommands

• af config get — Print one global or project-effective config value
• af config list — Print global or project-effective config values
• af config migrate — Rewrite deprecated config keys to their current spelling
• af config set — Set one global config key
• af config unset — Clear a config override or migrated global setting
• af config validate — Check that the global config parses and validates

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af config get

Print one global or project-effective config value

Print the effective value of one config key (e.g. default_program, auto_update, update_channel). By default the current repository's legacy, checked-in, and personal layers participate; outside git, the command falls back to global defaults. Run "af config list" to see every key. Scalar values print bare; composite values (program_overrides, root_agents, limit_patterns, keys) print as JSON.

Use --repo to inspect another project. The path is a selector only; this command does not register a project or write identity state. --project remains accepted as a deprecated alias. --explain prints the same resolved value with the complete source trace.

Local-only: it answers about the machine it runs on, so --daemon-url/AF_DAEMON_URL is refused rather than ignored. Run it on the daemon host to ask about that host.

af config get <key> [flags]

Flags

Flag	Type	Description
--explain		Show every source candidate and why it did or did not supply the value
--json		Emit the value(s) as JSON wrapped in the {data,error} envelope
--repo	string	Resolve config for this project instead of the current repository

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af config list

Print global or project-effective config values

Print every effective config key. By default the current repository's legacy, checked-in, and personal layers participate; outside git, the command falls back to global defaults. Pass --repo to inspect another project. --project remains accepted as a deprecated alias. --explain prints every source candidate and the reason it won, was shadowed, was absent, or is disallowed for that key. Human output renders an empty built-in value as "(unset)"; an explicitly configured empty value remains visible as "", [], {}, or null. JSON output preserves the typed effective values.

Local-only: it answers about the machine it runs on, so --daemon-url/AF_DAEMON_URL is refused rather than ignored. Run it on the daemon host to ask about that host.

af config list [flags]

Flags

Flag	Type	Description
--explain		Show every source candidate and why it did or did not supply each value
--json		Emit the value(s) as JSON wrapped in the {data,error} envelope
--repo	string	Resolve config for this project instead of the current repository

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af config migrate

Rewrite deprecated config keys to their current spelling

Rewrite the deprecated keys in the global config to their current spelling, in place, and print the diff. This is the command the deprecated-key warnings name.

It changes spelling, never meaning. A value written on one line is carried over exactly as its own bytes, quoting and all; a value spread over several lines (an array, typically) is re-encoded compactly rather than relocated as raw text, so its formatting can change even though its contents do not. Either way the rewritten file is re-parsed before anything is saved, and a rewrite that would change even one effective value is refused rather than written. The readers of the old spellings stay, so an older config keeps loading and nothing about your running configuration changes.

One thing to know before you DOWNGRADE. The grouped spellings have only been read since 2026-08-14 (#3354); an af older than that does not know them and falls back to the built-in default for a migrated key. For most keys that default is the conservative one (strict host-key checking, no credential mount). Two cases are not, both because the listener defaults to a LIVE 127.0.0.1:8443: migrating network.require_token = true loses the token an older binary could read (network.require_loopback_token only matters alongside it, being inert on its own), and migrating an empty network.listen_addr hides the fact that the web server was turned OFF, so an older binary starts one. Migrate compares what such a binary saw before and after, and says so explicitly when a migration costs you either. Restore the backup before such a downgrade.

The previous file is kept beside it as config.toml.bak (an existing backup is never overwritten; the copy is numbered instead). A legacy config.json is converted to config.toml on the way in, exactly as any af start would convert it.

Running it twice is safe: the second run finds nothing to migrate.

Two things it will not do:

A key written in BOTH spellings with different values is refused, naming the key. af has a documented winner at load time — the grouped value — but no migration should make that tie-break permanent on your behalf.

root_agents is reported and left exactly where it is. Its successor is a registered project's personal [root_agent], so migrating it would mean registering projects for you: durable state outside this file. The keys that can move still move.

Local-only: it rewrites the file on the machine it runs on, so --daemon-url/AF_DAEMON_URL is refused rather than ignored. Run it on the daemon host to migrate that host.

af config migrate [flags]

Flags

Flag	Type	Description
--json		Emit the migration result wrapped in the {data,error} envelope

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af config set

Set one global config key

Write one key into the global config.toml, editing only that value in place — preserving every unrelated comment, blank line, section header, and key ordering (the file is not regenerated). Every global config key is settable. Scalar values use their ordinary text form; tables and non-comma lists use compact JSON. Values are validated with the same rules the config loader uses before anything is written, so set can never leave a config that fails to load.

Settable keys: default_program agent enum (claude, codex, aider, gemini, amp, opencode, devin) program_overrides compact JSON object of agent-to-command entries program_overrides. full command string for an agent session_env_passthrough compact JSON array of exact environment variable names root_agents compact JSON object keyed by repository path root_agent compact JSON object with enabled and optional program root_agent.enabled true | false root_agent.program full command string for the singleton root agent keys compact JSON object of TUI action-to-key rebinds auto_update true | false network.listen_addr host:port serving the web UI + API, or "" to turn the web server off. warning: a non-loopback address (0.0.0.0, a LAN/Tailscale IP) puts af's full control plane on the network, and network.require_token defaults to false — set network.require_token = true in the same breath, or anyone who can reach the address controls this machine. af serves plain HTTP, so front a routable listener with a TLS-terminating proxy or a private network. network.require_token true | false (default false: the web UI needs no token; set true to require one from network peers) network.require_loopback_token true | false (default false: also require the token from same-machine browsers; only has an effect with network.require_token = true) network.preview_listen_addr host:port for a separate per-tab web-tab preview origin (and, on a loopback fixed port, a per-session VS Code editor origin), or "" to disable (default ""). Kept apart from network.listen_addr on purpose: it serves previews/editors only, never the control API. Same address grammar as network.listen_addr. daemon_poll_interval Go duration (e.g. 1500ms or 30m), or legacy positive integer (ms) watcher_events_per_minute positive integer (per-task watch delivery cap; default 10; next daemon start) debug_pprof true | false (serve Go runtime profiles at GET /v1/debug/pprof/{profile}; default false, unix control socket only, never on the web address. A profile dumps live daemon memory — session titles, worktree paths, prompt text — so turn it off again. AF_DEBUG_PPROF=1 overrides it for one daemon process. Next daemon start.) log_max_size_mb positive integer log_max_backups non-negative integer branch_prefix string on_archive_command shell command run before a local worktree moves into the archive, or "" to disable worktree_root subdirectory | sibling detach_keys string (e.g. ctrl-w) update_channel stable | preview vscode_server_binary path to the binary a VS Code tab runs, or "" to detect one on PATH limit_auto_resume true | false limit_account_candidates comma-separated registered account names, or "" to disable account switching limit_retry_interval Go duration (e.g. 30m), or "" to never retry limit_patterns compact JSON object of agent-to-regex entries limit_patterns. usage-limit banner regex for an agent global_agent_skills true | false docker.mount_agent_credentials true | false (let a docker session mount the operator's credential for that session's own agent, read-only) ssh.host_key_verification strict | accept-new | insecure (how the ssh backend verifies a remote host key; strict is the default) network.cors_allowed_origins comma-separated browser origins (scheme://host[:port]) allowed to call the API cross-origin, or "" to allow none — the whole list is replaced sandbox.ssh the ssh command the sandbox backend runs to reach the sandbox host (global-only: af runs it on the daemon host)

Legacy CLI aliases listen_addr, preview_listen_addr, require_token, require_loopback_token, cors_allowed_origins, docker_mount_agent_credentials, ssh_host_key_verification, and sandbox_ssh remain accepted and edit the same canonical grouped values.

Structured values must be shell-quoted so the JSON remains one argument. A write uses the same apply-on-save path as the TUI and web config panes (#2480). Most keys apply to the running daemon immediately; each successful set prints its exact effect notice.

With --project the value is written to a registered project's machine-local config instead of the global file, as a personal override that beats the checked-in in-repo value on this machine and is never committed. Only the preference keys the manifest admits per project are accepted there (default_program, program_overrides, program_overrides., default_accounts, default_accounts., root_agent, root_agent.enabled, root_agent.program, branch_prefix, on_archive_command); a global-only key is rejected with the location it actually belongs to. Clear an override with 'af config unset --project '.

Examples: af config set default_program codex af config set auto_update false af config set appearance dark af config set session_env_passthrough '["HTTP_PROXY","NO_PROXY"]' af config set root_agent.enabled true --project . af config set root_agent.program "codex --profile work" --project . af config set keys '{"quit":"Q"}' af config set program_overrides.claude "/usr/local/bin/claude --verbose" af config set default_program codex --project ~/work/myrepo af config set default_accounts.codex work --project ~/work/myrepo af config unset default_program --project ~/work/myrepo

With --daemon-url/AF_DAEMON_URL naming a remote daemon, the global write is sent to THAT daemon's admission-gated write — the same one the web config form posts to — and the success line names the daemon it landed on. It is never silently applied to this machine instead: a daemon too old to serve the route is refused, not written around. --project is the exception and stays local-only, because it writes a registered project's machine-local override file, which no remote daemon owns.

af config set <key> <value> [flags]

Flags

Flag	Type	Description
--json		Emit the value(s) as JSON wrapped in the {data,error} envelope
--project	string	Write to this project's machine-local config instead of the global config (a prj_ id or a repository path)

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af config unset

Clear a config override or migrated global setting

Remove one key's personal override for a project so the value falls back to the lower layers again (built-in < global < in-repo). Clearing an override is deliberately different from setting a value equal to the lower layer, which is still a present, winning override.

With --project, unset targets a project's machine-local config (a prj_ id from 'af projects list', or a path inside a registered repository). Without --project, it clears one migrated global backend setting: docker.mount_agent_credentials, ssh.host_key_verification, or sandbox.ssh. Their legacy flat CLI names are accepted aliases. Global unset removes both on-disk spellings together, so a conflicting legacy value cannot silently reappear. Every path edits only the target setting, preserves unknown keys and comments, and is a clean no-op when there is nothing to clear.

With --daemon-url/AF_DAEMON_URL naming a remote daemon, the global form is sent to THAT daemon's admission-gated write, like 'af config set'; a daemon too old to serve the route is refused rather than written around, so a remote unset never quietly clears a key on this machine instead. --project stays local-only — the override file it clears is this machine's.

af config unset <key> [flags]

Flags

Flag	Type	Description
--json		Emit the value(s) as JSON wrapped in the {data,error} envelope
--project	string	The project whose override to clear (a prj_ id or a repository path)

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af config validate

Check that the global config parses and validates

Read the global config (~/.agent-factory/config.toml) exactly as af and the daemon do at startup and report whether it loads. It writes nothing and materializes nothing — a read-only check.

This is the companion to a raw hand-edit. "af config set" validates every scalar and structured key before it writes and so cannot leave a broken file. A manual edit bypasses that protection: exit 0 means no config defect was found, while a non-zero exit names what must be fixed before the next launch.

Local-only: it checks the config on the machine it runs on, so --daemon-url/AF_DAEMON_URL is refused rather than ignored. Run it on the daemon host to check that host.

af config validate [flags]

Flags

Flag	Type	Description
--json		Emit the value(s) as JSON wrapped in the {data,error} envelope

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af daemon

Manage the background daemon: serves the web UI and schedules tasks

The agent-factory daemon runs task cron schedules in-process, supervises watch-task scripts, monitors sessions, and serves the bundled web UI.

The web UI is part of the daemon — there is no separate web command — so it is served whenever the daemon is running. Running af starts one: the TUI reads session state through the daemon and spawns it if none is up, so simply opening af serves the web UI. Any enabled task starts one too. Only standalone commands that never talk to the daemon (such as 'af config list') leave it down.

With af running, open:

http://localhost:8443

It needs no token by default, so the page connects as soon as it loads. Set network.listen_addr to change the address (or to "" to turn the web server off). network.require_token = true demands a bearer token ('af token show') from network peers; on the default loopback listener same-host callers stay exempt, so the UI keeps opening with no login on this machine. Add network.require_loopback_token = true to require the token from localhost as well. Note that 'af agent-server' does not serve the web UI: it is the headless per-workspace backend a daemon drives on a remote machine.

Clients reach the daemon over a local Unix socket by default. To drive one from another machine, either ssh to that host and run 'af' there, or give network.listen_addr a routable address and point a client at it with the persistent --daemon-url and --token flags. A routable listener is allowed with the token off, but af warns once at daemon start: with network.require_token = false anyone who can reach the address drives your agents, so set network.require_token = true unless you trust the network. That listener speaks plain HTTP either way, so put it behind a reverse proxy or a private network (Tailscale/VPN) if you need TLS. Full guide: https://sachiniyer.github.io/agent-factory/remote-http-auth/

Install the daemon as a user-level autostart unit (systemd user service on Linux, launchd agent on macOS) so tasks keep firing and the web UI stays up after reboots, even when af is never opened:

af daemon install

af daemon

Subcommands

• af daemon adopt — Hand a detached daemon back to the installed autostart unit
• af daemon install — Register the daemon to start automatically at login
• af daemon restart — Restart the running daemon without stopping live sessions
• af daemon status — Report daemon liveness, config freshness, and supervision
• af daemon uninstall — Remove the daemon autostart unit

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af daemon adopt

Hand a detached daemon back to the installed autostart unit

Reclaim supervision of the background daemon for the installed autostart unit.

When a daemon is running detached from its unit — an ad-hoc child a live af spawned, which the service manager can no longer restart — adopt stops that daemon and starts the installed unit in its place, then verifies the unit now owns the process answering the control socket. Live sessions keep running in tmux; the new supervised daemon re-adopts persisted session state on startup, exactly as 'af daemon restart' does.

It needs an installed unit that serves this home ('af daemon install'); with no such unit there is nothing to adopt the daemon into. If the installed unit already owns the running daemon, adopt reports that and changes nothing.

af daemon adopt [flags]

Flags

Flag	Type	Description
--force		displace the running daemon even if af cannot confirm it is unsupervised (you assert it is yours to replace)

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af daemon install

Register the daemon to start automatically at login

af daemon install

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af daemon restart

Restart the running daemon without stopping live sessions

Restart the background daemon if one is running. Live sessions keep running in tmux; the new daemon re-adopts persisted session state on startup. If no daemon is running, this command exits successfully without starting one.

af daemon restart [flags]

Flags

Flag	Type	Description
--quiet		Suppress output when no daemon is running

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af daemon status

Report daemon liveness, config freshness, and supervision

Print a read-only snapshot of the background daemon: whether it is responding on the control socket, the control and HTTP socket paths (and whether their files are present), the recorded and responding pids, whether the installed autostart unit owns that responding process, whether the config on disk matches what the daemon booted with, and whether the running binary was replaced.

It never contacts a paused daemon in a way that spawns one and never starts the daemon. Service-manager inspection is bounded and read-only. Use --json for a machine-readable form wrapped in the shared {data,error} envelope.

af daemon status [flags]

Flags

Flag	Type	Description
--json		Emit the status as JSON wrapped in the {data,error} envelope

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af daemon uninstall

Remove the daemon autostart unit

af daemon uninstall

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af debug

Print debug information like config paths

af debug

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af doctor

Diagnose setup, daemon health, and leaked session resources

Diagnose the local agent-factory environment.

For first-run setup checks, use:

af doctor --setup

The setup profile checks the prerequisites needed to create the first local session: AF home writability, config materialization and parsing, git and the current repo, git identity, tmux, configured agent commands, state/log storage, daemon health, and remote-hook setup when this repo configures it.

Without --setup, doctor runs the full maintenance sweep for problems that accumulate silently on a machine running agent-factory:

• orphaned processes spawned by sessions that no longer exist
• processes that escaped a live session's pane, or peg a CPU core for hours
• af_ tmux sessions with no backing session record
• abandoned agent-factory homes under the temp dir (leaked by tests/debug runs)
• af daemons running a binary no install owns — one under the temp dir, or one whose file is gone from disk. A temp-dir binary is debris a test or debug run left behind; --fix stops it once it is old enough that no test run can still own it, and never when it serves this home or when which home it serves cannot be read. A missing binary is reported, not stopped: af upgrade replaces it in place, so every healthy daemon looks that way until it restarts
• temp directories holding nothing but a daemon socket nobody answers on — the residue an abandoned daemon's bind left behind. --fix removes one with os.Remove rather than a recursive delete, so a directory that has gained anything since the scan fails instead of being swept up with it
• directories af's own test harness left under the temp dir when a test run ended before its cleanup (af-test-home-, af-test-user-home-, af-tmux-pkg-, af-tmux-, ...). --fix removes one only when it holds nothing but that run's leftover harness content, has not changed for a week, and no live process has a file open in it, names it, or works inside it — entry by entry with os.Remove, never a recursive delete. Anything else in one is reported, and a tmux server still answering in one is named rather than stopped
• daemon health: control socket, autostart unit, pid file, binary freshness
• client/daemon version skew, and the ways a stale daemon survives an upgrade: a second daemon on this home, an autostart unit launching a different af binary than yours, several af installs at different versions, sockets left behind with no daemon answering, and an autostart unit that is installed but not actually supervising anything
• remote-hook setup for the current repo: config completeness and launch_cmd/delete_cmd script presence/executability (skipped cleanly when no remote backend is configured)
• pinned remote host-key directories under hook-hosts/ that no session owns. Hook names are one namespace for the whole machine, so this one spans every project rather than the current repo, and it runs whether or not this repo configures a remote backend. --fix removes a directory only on proof that no session owns it — live, archived, mid-kill and awaiting-teardown sessions all count — and removes nothing at all when any part of that inventory cannot be read

The version-skew check exists because a skewed daemon fails quietly: it keeps answering while rejecting fields a newer client sends, which surfaces as "unknown field " and a hung UI rather than as an upgrade prompt.

Use --json to emit each check as {name, section, status, detail, remedy, actionable} in the shared {data,error} envelope for scripting. Branch on "actionable", not on the status or whether --fix supports the row. Actionable means doctor established a specific unhealthy condition and named a correction that must happen before the run is healthy. Some exact corrections are manual and remain actionable even though --fix does not perform them.

UNKNOWN observations stay visible as advisory warnings with inspection guidance, but they are not actionable: "inspect it and decide" is not a finding that the run is unhealthy. A CI step or health probe should fail on the command exit code: 1 means unresolved actionable issues remain or a check did not finish looking. Advisory warnings alone do not fail the run.

A check that stops early — for example, the temp-home sweep hits a candidate budget on a machine with a very large temp dir — now exits 1 even if it found no unhealthy condition. The summary line ends with "INCOMPLETE" naming the checks that gave up, and summary.incomplete lists them in --json. The exit code already covers incomplete checks, so a plain-exit-code probe needs no extra JSON check. To distinguish the exit-1 cases, read summary.unresolved and summary.incomplete under data in the JSON envelope: exit status -eq 1 with unresolved == 0 means incomplete; unresolved > 0 means actionable issues remain (and summary.incomplete may also be non-empty).

High-volume findings are summarized by default so the actionable problem is visible first — process findings, abandoned temp homes, dead-socket directories, and test-harness directories, all of which run to hundreds or thousands on a busy machine. Use --verbose to show each item behind those summaries. A summary from a check that did not finish reads "at least N … a lower bound" in its own row, so its count is never mistaken for the total.

Read-only by default. With --fix, applies the safe remediations — killing orphans whose ancestry markers prove they came from a dead af session, removing stale temp homes, stopping daemons proven to be running a temp-dir binary, removing directories holding nothing but a dead daemon socket, and removing the test-harness directories described above — logging each action. Ambiguous cases are always reported rather than acted on, and remain advisory unless another check establishes a specific unhealthy condition.

Exits 1 when unresolved actionable issues remain or summary.incomplete is non-empty. Exits 0 when no actionable issues remain and no checks are incomplete (advisory warnings may still be present).

af doctor [flags]

Flags

Flag	Type	Description
--fix		apply safe remediations (kill verified orphans and leaked daemons, remove stale temp homes and dead-socket dirs)
--json		emit each check as JSON in the {data,error} envelope
--setup		run the first-run setup profile (prerequisites, config, agent commands)
--verbose		show per-process doctor findings instead of collapsed summaries

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af keys

Show the effective TUI key bindings (defaults plus [keys] rebinds)

Show every TUI action with its effective key binding: the built-in default, or the rebind from the [keys] table in config.toml (#1026). Fixed bindings — structural keys config cannot touch — are listed last. Contextual pane actions such as pane_prev/pane_next are included; their default arrow keys apply only while a workspace pane has focus.

Every default key removed by a user rebind is named in SOURCE with its taker. The affected row keeps any remaining keys; when none remain, it shows an em dash instead. JSON appends the same key/taker pairs in suppressed_by.

Key values use config spellings you can paste into [keys]. With --json, bindings are wrapped in {data,error}; keys/default keep those spellings.

af keys [flags]

Flags

Flag	Type	Description
--json		Wrap output in the {data,error} JSON envelope

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af projects

Manage projects and durable registrations

af projects

Subcommands

• af projects add — Add a project: register a repo by path with a stable local identity
• af projects delete — Delete a project, archiving its restorable sessions
• af projects list — List registered projects
• af projects rebind — Rebind a registered project after its checkout moves

Flags

Flag	Type	Description
--json		Wrap output in the {data,error} JSON envelope (default: bare payload)

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af projects add

Add a project: register a repo by path with a stable local identity

Add a project by registering a git checkout with a stable, machine-local identity, so it appears as an (initially sessionless) project you can create sessions into.

The path may be relative (including '.'), absolute, or start with ~. A relative path or '~' is resolved against YOUR shell's working directory before the request is sent — so 'af projects add .' registers the repo you are standing in. The daemon then walks to the checkout's canonical main-repo root and validates it is a git repository (an actionable error otherwise). Any directory inside a checkout resolves to that root. Registration is idempotent: adding a known checkout is a no-op success that returns its existing identity.

The returned project id survives an explicit rebind after the checkout moves. Two clones remain separate projects. Identity is anchored in an AF-home-scoped agent-factory/checkout-id- marker under the Git common directory, so one AF home's reset cannot remove another home's identity. No working-tree file is created, and adding a project does NOT start an always-on agent for it.

'register' is a deprecated alias for 'add'.

af projects add <path>

Aliases: register

Global flags

Flag	Type	Description
--daemon-url	string	Target a REMOTE daemon at this http:// or ws:// URL instead of the local unix socket (env: AF_DAEMON_URL). The daemon is HTTP-only; terminate TLS at your own proxy if needed.
--json		Wrap output in the {data,error} JSON envelope (default: bare payload)
--token	string	Bearer token for a remote daemon set with --daemon-url (env: AF_DAEMON_TOKEN). Get it with 'af token show' on the daemon host.

af projects delete

Delete a project, archiving its restorable sessions

Delete a project for a git repository and remove its live sessions.

Every regular worktree session is archived (its tmux is torn down and its worktree moved to the archive dir, but its branch and uncommitted changes are preserved). The always-on root agent (if any) is stopped and its root-agent opt-in removed. In-place sessions (the root agent, 'af sessions create --here') are torn down instead of archived — their cleanup never touches your working tree or branch.

The durable project registration, if any, is removed so the project leaves the project list. Restoring an archived session makes its repository active again, but does not restore the durable registration or root-agent opt-in.

Your real git repository is never touched. To undo a mis-click, restore any archived session with 'af sessions restore