CLI reference

Every command, one line each. Run alkahest <command> --help for flags and subcommands.

Core

Command	What it does
alkahest scan	Parse the source and build .alkahest/map.json (local, static analysis).
alkahest login --token alk_…	Link the CLI to your account (tokens: alkahest.app → API tokens). Run it bare to see the state you are already in.
alkahest status	Are you signed in, and where does this checkout publish? Token, API, workspaces, and the project/map this folder is linked to.
alkahest logout	Forget the saved token. Local only — revoke it at alkahest.app → API tokens to cut it off on the server.
alkahest publish	Upload the map and get/update the shareable link. --map <slug> targets one of several code maps; --slug targets a project explicitly. Prints a "⏳ waiting on you" line when decisions or assignments await you.
alkahest update	Update the CLI to the latest release (--check to only look).

Issues

alkahest issues … — the dependency-first tracker from the terminal:

Subcommand	What it does
pull	List issues with derived state (ready / blocked / done / awaiting decision).
add <title>	File an issue (--type, --status, --parent, --blocks, …).
status / priority / due / assign	Triage fields.
done <id>	Mark complete.
link / rm	Add or remove blocks / contains / relates edges.
map <id>	Put an issue on an issue map, or take it off (--map <slug>, --remove).
comments <id>	Read an issue's thread.
comment / reply / resolve	Write to the thread; resolve closes a decision question.

Notes

Subcommand	What it does
notes add <title>	Create a note (--body / --body-file markdown, --folder for a tree path).
notes list / show	Browse and read.
notes update	Edit title/body, move it in the tree (--folder / --unfile).
notes link <slug> <target>	Connect a note to an issue:<id> or code:<node>. Note ↔ note links are just [[Title]] refs in the body — write them in the text.
notes map <note> --map <slug>	Move a note to another notebook (a note lives on exactly one note map).
notes import <dir>	Mirror a folder of Obsidian-style .md files — one note per file, frontmatter becomes properties, [[wikilinks]] render as links. Re-run to sync — matching is source-path-first, so retitled docs update in place (guide).

Docs presets

Command	What it does
alkahest presets	List the installable docs presets.
alkahest docs init	Install a preset — writing-instruction skills on your account, a docs/ scaffold, a reference sync script, the note maps, and an opt-in agent-rules snippet. Idempotent: existing skills and files are kept (--force to overwrite skills). See Note recipes.

Maps & projects

Command	What it does
alkahest maps list / create	See a project's maps, add one (`--type code
alkahest projects	List projects you can publish to.
alkahest history	The publish timeline (versions + node diffs).
alkahest comments pull	Read code-map comments from the terminal.

Agent plumbing

Command	What it does
alkahest mcp	Run the MCP server — see Set up your agent.
alkahest hook	Print shell-hook helpers for agent integrations.