Skip to content
The Librarian

CLI

The Librarian ships two command-line tools. librarian runs on a client or host machine to install the integration into your harnesses and, optionally, to self-host the server. the-librarian runs against the memory vault itself for backups, exports, handoff inspection, and auth recovery.

librarian — install and self-host

Section titled “librarian — install and self-host”
Usage: librarian <command> [harness…] [flags]


Commands:
  install   [harness…]   Install The Librarian into one or more harnesses
  uninstall [harness…]   Remove The Librarian from one or more harnesses
  update    [harness…]   Update the integration to the current version
  status                 Live table of harness / installed / version
  doctor                 Diagnose token, server reachability, harness CLIs
  config                 Show or set MCP URL, token, server URL
  server                 Self-host the Librarian server (run `server` for its commands)
  self-update            Update the librarian CLI itself
  report                 Push this machine's state to the server


Flags:
  --mcp-url <url>        config: set the MCP endpoint URL
  --token <token>        config: set the bearer token (never printed)
  --shell <bash|zsh|fish>  override shell detection for the rc block
  -h, --help            Show this help
  -v, --version         Show the CLI version


Harnesses: claude, codex, opencode, hermes, pi

librarian server

Section titled “librarian server”
Usage: librarian server <subcommand> [flags]


Self-host the Librarian server (build + run the all-in-one container),
then hand its MCP URL + agent token to `librarian install` on clients.


Subcommands:
  up            Build + run the server; print the MCP URL + agent token
  update        Re-pin to a release, rebuild, recreate (data volume kept)
  down          Stop the container (the data volume is preserved)
  status        Running? healthy? deployed version vs latest release
  logs          Tail the container logs ([-f] [--service mcp|dashboard|all])
  enable-boot   Start the server on boot (Linux systemd; macOS deferred)
  disable-boot  Reverse enable-boot
  autoupdate    Schedule auto-updates on the host (enable|disable|uninstall|status)
  admin         Run an admin command in the container (backup|restore|auth|rebuild)


Run `librarian server <subcommand> --help` for flags (per subcommand).

the-librarian — server-side admin

Section titled “the-librarian — server-side admin”
Usage: the-librarian <command>


Commands:
  rebuild                       Rebuild the memory index from stored data
  seed                          Seed sample memories (no-op if any exist)
  backup                        Push the memory vault to the configured GitHub remote
  restore [--secret-key <hex>] [--force]
                                Clone the backup remote into the data dir (re-supply the master key)
  export [--format ndjson|json] Dump memories to stdout
  migrate-data-dir [--data-dir <path>]
                                Migrate a pre-1.0 data dir (reports, never deletes)
  handoffs <verb>               Inspect cross-harness handoffs (see 'handoffs help')
  auth <verb>                   Recover dashboard auth (see 'auth help')

the-librarian handoffs

Section titled “the-librarian handoffs”
Usage: the-librarian handoffs <verb> [args] [flags]


Verbs:
  list                          List handoffs (default: unclaimed)
  show <handoff_id>             Show a single handoff (including its document)
  purge <handoff_id>            Admin-only — hard-delete a handoff row


Common flags:
  --project <key>               Filter by project_key
  --cwd <path>                  Filter by cwd
  --harness <name>              Filter by created_in_harness
  --limit <n>                   list: max rows (default 20, max 100)
  --include-claimed             list: include already-claimed handoffs (default: hide)
  --admin                       purge: required
  --json                        Emit JSON instead of prose

the-librarian auth

Section titled “the-librarian auth”
Usage: the-librarian auth <verb> [flags]


Verbs:
  status                        Show configured methods + enforcement (no secrets)
  reset-password                Set a new owner password and clear lockout
  disable                       Turn off enforcement (break-glass)


Flags:
  --json                        status: emit JSON instead of prose
  --username <name>             reset-password: owner username (default: the configured one)
  --password <pw>               reset-password: new password (omit to be prompted, no echo)
  --print-setup-link            reset-password: mint a one-time browser link instead
  --origin <url>                reset-password: dashboard origin for the printed link