Gandalf CLI reference overview - Gandalf

Gandalf is a single binary with three groups of commands: skill management and session distilling, which are stateless, and work handoff, which talks to a local background service.

Skill commands

Command	Description
`gandalf`	List skills and how they line up across agents. Same as `gandalf skill list`.
`gandalf skill list`	List skills and how they line up across agents.
`gandalf skill show <name>`	Show where a skill is installed and print its `SKILL.md`.
`gandalf skill add <path>`	Install a local skill directory into your agents.
`gandalf skill sync [name...]`	Copy skills to the agents that are missing them.
`gandalf skill remove <name>`	Remove a skill from your agents.
`gandalf tui`	Review skill drafts and installed skills in a terminal UI.

Sessions to skills

Command	Description
`gandalf distill`	Turn this project’s recent sessions into lessons, using your own coding agent.
`gandalf suggest`	Group the lessons into skill drafts you can review and install.

Work handoff commands

Command	Description
`gandalf init`	Connect Claude Code and Codex and install the background service.
`gandalf status`, `gandalf doctor`	Check the service and the local installation.
`gandalf daemon`	Start, stop, or read the logs of the background service.
`gandalf work`	List and show tracked work in this project.
`gandalf handoff <id>`	Print the handoff contract for one piece of work.
`gandalf search <query>`	Search what you and your agents said and did in this project’s sessions.
`gandalf evidence <id>`	Show one piece of recorded evidence.
`gandalf tui --work`	Browse tracked work in a terminal UI.
`gandalf mcp`	Serve handoff context to an agent over MCP.
`gandalf agent`	List, connect, or disconnect agents.
`gandalf config`	Show or change settings.
`gandalf forget`	Delete recorded work or all data for this project.

Global flags

Flag	Description	Default
`--output <format>`	`text` or `json`.	`text`
`--project-root <dir>`	Project directory.	Current directory

Gandalf uses $HOME to find agent directories and its own data.

Skill flags

Available on every gandalf skill command:

Flag	Description	Default
`--scope <scope>`	`user` or `project`. `list` also accepts `all`.	`user`
`--agent <agent>`	Limit to these agents: `claude-code`, `codex`, `cursor`. Repeat or comma-separate.	Agents with a config directory in your home

Exit codes

Code	Meaning
`0`	Success.
`1`	A skill command failed, or refused a change (a differing copy without `--from` or `--force`).
`2`	Invalid arguments.
`69`	A handoff command could not reach the background service or was given an invalid project or identifier.