cli.md

title	Command line (CLI)
sidebar_label	Command line (CLI)

Command line (CLI)

What it's for: querying and managing your coaching data from the terminal — quick lookups, scripting, backups, and tuning settings without leaving the shell. It's a power-user companion to the automatic coaching in your agent; everything here is also available in the web dashboard.

:::tip[Using the Claude Code plugin?] The plugin does the coaching by itself and does not put devcoach on your PATH, but the CLI is a useful companion whenever you want the dashboard or your data without going through Claude — devcoach ui, stats, lessons, share / import, backup. Run it with npx -y devcoach …, or install Homebrew / npm i -g devcoach for a bare command. Two commands are not for plugin users: devcoach install and devcoach uninstall — the plugin owns the hooks and the skill (/plugin uninstall devcoach@ultimaphoenix removes them). :::

Built on Commander, so every command supports --help.

devcoach --help              # list all commands
devcoach <command> --help    # usage for one command
devcoach --version

Prefix any command with npx -y if you haven't installed globally (npm i -g devcoach). Mutating commands write to ~/.devcoach/coaching.db; sandbox them with DEVCOACH_DIR=$(mktemp -d) devcoach ….

Setup & integration

Command	Description
devcoach mcp	Start the MCP server (stdio) — used by your agent's MCP config
devcoach install [--claude-code] [--claude-desktop] [--gemini] [--codex] [--force] [--skip-hook]	Register the MCP server (user scope) + hooks + skill for the chosen agents; repairs stale hook layouts
devcoach uninstall [--claude-code] [--claude-desktop] [--gemini] [--codex] [--all] [--data] [--yes]	The inverse of install: removes the MCP registration, the devcoach hook entries and the skill dirs (user hooks untouched); --data also deletes ~/.devcoach after a prompt. Run it before brew uninstall / npm uninstall -g
devcoach doctor	Diagnose the wiring and the pacing state: hooks, skill, and the command each agent starts devcoach with (Claude Code; Claude Desktop, resolved on the PATH from Claude Desktop's own log; Gemini and Codex when present) — that it exists, which Node it runs on and which devcoach version — then explains why the next stop would or wouldn't cue a lesson
devcoach setup	Interactive terminal onboarding wizard in four steps: backup path (or skip) → automatic or manual topics → optional groups → daily limit and minimum gap
devcoach ui [--port <n>] [--open]	Launch the web dashboard (default port 7860; binds 127.0.0.1 only). The URL is printed as a clickable terminal link; --open also launches your default browser. Ctrl+C stops it gracefully (in-flight requests finish)
devcoach ui --stop [--port <n>]	Stop the dashboard listening on that port — yours, or one your agent started with open_ui / /devcoach:ui (those run detached, so Ctrl+C cannot reach them)
devcoach stop-hook / prompt-hook	Claude Code hooks (hidden from --help): Stop (onboarding check + lesson cue) and UserPromptSubmit (priming). Exit 0 always; silent or a JSON directive on stdout. Trace decisions with DEVCOACH_HOOK_DEBUG=1
devcoach gemini-stop-hook / gemini-prompt-hook	The same pair for Gemini CLI (beta), registered by install --gemini
devcoach codex-stop-hook / codex-prompt-hook	The same pair for Codex (beta), registered by install --codex
devcoach onboard-hook / lesson-ready	Legacy two-entry Stop hooks (still supported; install migrates to stop-hook)

Knowledge map

Command	Description
devcoach profile	Show the knowledge map with confidence bars
devcoach knowledge-add <topic> [--confidence <0-10>] [--group <name>]	Add or update a topic
devcoach knowledge-remove <topic>	Remove a topic
devcoach group-add <name> / group-remove <name>	Create / delete a group
devcoach group-assign <topic> <group>	Move a topic to a group (Other to ungroup)

Lessons

Command	Description
devcoach lessons [--period <p>] [--level <l>] [--category <c>] [--project/--repository/--branch/--commit <…>] [--starred] [--imported] [--from <name>] [--feedback <f>] [--date-from/--date-to <YYYY-MM-DD>] [--sort <col>] [--order <asc|desc>]	List lessons with filters
devcoach lesson <id>	Show a single lesson in full
devcoach star <id> / unstar <id>	Star / unstar
devcoach delete <id>	Permanently delete a lesson
devcoach feedback <id> <know|understood|dont_know|clear>	Record your answer under a lesson (know adjusts confidence)
devcoach courses	List your step-by-step courses with progress
devcoach course <id>	Show a course: chain, steps, progress, where its document lives
devcoach share [id] [--last] [--link] [--file [path]] [--with-context] [--by <name> | --anonymous]	Hand a lesson to a teammate — see Sharing a lesson
devcoach import [source]	Add a shared lesson — code, card text, link, URL, .devcoach.md, JSON export, - for stdin; no argument reads the clipboard

Stats & settings

Command	Description
devcoach stats	Lesson counts, rate-limit status, weakest/strongest topics
devcoach settings	Show current settings — max_per_day, min_gap_minutes, nudge_every, nudge_scope, share_name
devcoach set max_per_day <n>	Max lessons per 24h (1–20, default 2)
devcoach set min_gap_minutes <n>	Minimum minutes between lessons (0–1440, default 240)
devcoach set nudge_every <n>	Interactions between lesson cues (0–1000, default 10; 0 = every turn)
devcoach set nudge_scope <session|global>	Count interactions per chat session (default) or globally
devcoach set share_name <name>	The sender name proposed by share (max 80 chars; empty clears → git user.name)

Backup, export & import

Your whole profile lives in one place, so moving it between machines is a single command each way.

# Export everything → a portable zip (settings + knowledge map + lessons + notebook)
devcoach backup ~/devcoach-$(date +%F).zip   # default file: devcoach-backup.zip

# Import on another machine (or restore after a reset)
devcoach restore ~/devcoach-2026-06-19.zip

Command	Description
devcoach backup [file.zip]	Export settings + knowledge map + lessons + notebook (default devcoach-backup.zip)
devcoach restore <file.zip>	Import a backup — settings overwritten, knowledge upserted, duplicate lessons skipped

On restore, your profile and full lesson history are merged in; you can also point the onboarding wizard at a backup. The same export/import is available in the web dashboard's Settings page. For the zip's internal format, see Configuration & data.

Sharing a lesson

One lesson, three transports — the receiver never has to tell them apart:

devcoach share --last                 # the card + one devcoach:lesson:1:… line → paste anywhere
devcoach share <id> --link            # https://ultimaphoenix.github.io/dev-coach/lesson#devcoach:lesson:1:…
devcoach share <id> --file            # writes <id>.devcoach.md (YAML front matter + markdown)
devcoach share <id> --with-context    # also project/branch/commit/task — never a local folder path
devcoach share <id> --by "Ada" | --anonymous   # sender name (default: share_name → git user.name)

Receiving is one command, whatever you were given:

devcoach import                       # no argument: reads the clipboard
devcoach import lesson.devcoach.md    # a file
devcoach import "devcoach:lesson:1:…" # the code, or the whole copied card in quotes
devcoach import https://…             # a share link, or any URL whose body is a shared lesson
pbpaste | devcoach import -           # stdin

devcoach lessons --imported lists the lessons shared with you, --from <name> only those from one sender (the free-text search matches sender names too). What travels, the .devcoach.md format and how an imported lesson behaves (it never counts against max_per_day) are in the Sharing lessons guide. --by is remembered as share_name the first time (change it with devcoach set share_name).

Environment variables

Variable	Effect
DEVCOACH_DIR	Relocate the data directory (default ~/.devcoach) — sandboxing, tests, a second profile
DEVCOACH_HOOK_DEBUG=1	Trace every hook decision to ~/.devcoach/hook.log
NO_COLOR	Disable coloured terminal output

Examples

devcoach lessons --period week --level senior --starred
devcoach lessons --category docker --sort timestamp --order asc
devcoach feedback 9f3a know
devcoach set min_gap_minutes 120
devcoach backup ~/devcoach-$(date +%F).zip
devcoach share --last --link
devcoach import