Almanac CLI reference

almanac <command>

Almanac curates agent skills and indexes them for agents to read.

Global options

--root <dir>: the library directory, taken literally. The directory must hold almanac.yml. No walk, and no fallback.

--home: act on the configured root library, wherever the command runs.

--version: print the version and exit.

--help: print the help and exit.

Root resolution

Without --root, a command finds its library by one rule: the nearest almanac.yml at or above the working directory wins. The walk requires a regular file. It stops at the first directory the invoking user does not own, so a marker planted in a shared ancestor captures nothing.

With no library found, a read falls back to the root library set in ~/.config/almanac/config.yml, and it says so on stderr. A write never falls back. It fails and names --home.

No environment variable takes part in the resolution. The config path is fixed, and the home directory comes from the passwd database rather than from $HOME. A repository can set either channel, and neither one decides where a command writes.

A write prints its resolved target on stderr unless the target is the working directory’s own library or --root named it. A read resolved by walking or by fallback prints its source.

Library commands

These commands read and write almanac.yml. Read almanac docs curation for the manifest workflow and the trust model.

almanac init

Create an almanac.yml manifest that governs a library directory.

almanac init [--library <dir>]

almanac add <source>

Fetch a skill, print its red-flag report, and vendor it with --accept.

almanac add <source> [--name <name>] [--path <dir>] [--ref <ref>] [--rev <sha>] [--accept]

Without --accept, almanac stages the skill, prints the report, and exits 1. Nothing lands in the library.

almanac sync

Write every pinned entry to disk.

almanac sync [--check]

Each entry prints one line: ok, skip for a dev: snapshot, or FAIL.

almanac update [names...]

Fetch upstream, print the red flags and the diff, and re-pin with --yes.

almanac update [names...] [--yes]

Without --yes, almanac prints the report and changes nothing.

almanac remove <name>

Remove an entry and its vendored directory.

almanac remove <name>

Almanac refuses to delete a directory without an .almanac-origin stamp.

almanac status

List every manifest entry with its pin, its drift state, and its source. The drift state is clean, drifted, or missing. Unmanaged neighbor directories follow, marked unmanaged.

almanac status

Index commands

almanac list

List the available skills with name, description, and source type.

almanac list [--source <path>]

Output columns: NAME, DESCRIPTION, [SOURCE_TYPE]. Skills come from path sources (file). Nothing is compiled into the binary. The curated library is the main source. Read almanac docs curation.

almanac show <name>

Print the full SKILL.md content of one skill.

almanac show <name> [--source <path>]

Almanac prints the raw SKILL.md content to stdout. It exits with an error when the skill is not found.

almanac index

Print a JSON index of the available skills.

almanac index [--source <path>] [--md] [--max-bytes <n>]

The JSON output is an array of skill objects. Each object holds name, description, and source metadata.

Under the --md budget the output degrades in steps: full lines first, then names only, then a truncation note.

almanac prime

Print what almanac is and how to use it, for an agent’s context. The output depends only on the binary version: no arguments, config, or store changes it. Put it into an agent’s context; policy about when to use almanac belongs to the caller.

almanac docs

Read the bundled almanac documentation.

almanac docs                    List the available docs and their slugs
almanac docs list               Same as bare `almanac docs`
almanac docs <identifier>       Print one doc by slug, title, or unique prefix
almanac docs search <query>     List the docs that carry the query
almanac docs --all              Print every doc, in one stream

almanac serve

Serve this library over MCP. The server is read-only, and it has no authentication; almanac docs composition says what to put in front of it.

almanac serve [--surfaces <list>] [--bind <addr>]

almanac store list

List the libraries that this library reads, in precedence order. The first row is this library. Each other row shows a declared library, its source, and its skill count. A remote library also shows the age of its cache.

almanac store root

Show or set the root library that reads fall back to. almanac store root prints the current setting. almanac store root <path> writes it to ~/.config/almanac/config.yml. The path must hold almanac.yml, and a change to an existing setting needs --force.

Each tool keeps its own config file, so this setting names the root library for almanac alone. One repository can hold almanac.yml, tisket.yml, and zettel.yml, and be the root for each of the three.

almanac store sync

Fetch each declared remote library into the local cache. This command reaches the network, as add, update and sync also do. No other command does.

almanac check

Report the problems that the declarations create:

• A requires: entry names no skill.
• Two libraries hold one skill name. The report gives the library that wins and each library that loses.
• A declared library is not available.
• A file could not be read.
• In a shared: true library, a clone cannot reach a declared library.

The command exits non-zero when it finds any. Read almanac docs composition for the model.