--- title: "Almanac CLI reference" description: "Complete command reference for the almanac skill aggregator" type: reference canonical_url: https://almanac.eng.rip/cli-reference/ --- # Almanac CLI reference ``` almanac ``` Almanac curates agent skills and indexes them for agents to read. ## Global options `--root `: 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 ] ``` | Option | Description | |--------|-------------| | `--library ` | Library directory, relative to the manifest. Defaults to `skills` | ### `almanac add ` Fetch a skill, print its red-flag report, and vendor it with `--accept`. ``` almanac add [--name ] [--path ] [--ref ] [--rev ] [--accept] ``` | Argument/Option | Description | |-----------------|-------------| | `` | `github:owner/repo`, `owner/repo`, `git:`, or `dev:` | | `--name ` | Manifest name. Must match the SKILL.md frontmatter name | | `--path ` | Skill directory within the source | | `--ref ` | Branch or tag to resolve | | `--rev ` | Exact commit to pin | | `--accept` | Accept the staged content into the library | 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] ``` | Option | Description | |--------|-------------| | `--check` | Verify instead of writing. Exits 1 when a pinned entry drifts | 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] ``` | Argument/Option | Short | Description | |-----------------|-------|-------------| | `[names...]` | | Entry names. Defaults to every git-sourced entry | | `--yes` | `-y` | Apply the update and re-pin | Without `--yes`, almanac prints the report and changes nothing. ### `almanac remove ` Remove an entry and its vendored directory. ``` almanac remove ``` 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 ] ``` | Option | Short | Description | |--------|-------|-------------| | `--source ` | `-s` | Skill source directory. Repeatable. Each flag adds one source | 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 ` Print the full SKILL.md content of one skill. ``` almanac show [--source ] ``` | Argument/Option | Short | Description | |-----------------|-------|-------------| | `` | | Skill name to print | | `--source ` | `-s` | Skill source directory. Repeatable | 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 ] [--md] [--max-bytes ] ``` | Option | Short | Description | |--------|-------|-------------| | `--source ` | `-s` | Skill source directory. Repeatable | | `--md` | | Print a markdown index of the library instead. Reads `almanac.yml` | | `--max-bytes ` | | Byte budget for `--md`. Defaults to 4096 | 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 Print one doc by slug, title, or unique prefix almanac docs search 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 ] [--bind ] ``` | Option | Default | Description | |--------|---------|-------------| | `--surfaces ` | `skills,tools` | The surfaces to offer, separated by commas: `skills`, `resources`, `tools`. | | `--bind ` | (none) | Where to listen, for a client that connects over HTTP. Omitted, the server speaks on stdin and stdout for a client that starts it. | ## `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 ` 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.