@ai-dossier/cli

Install, verify, and publish dossiers — portable, signed, versioned skills — for any LLM tool.

A dossier is a skill with trust built in. This CLI is how you author them, verify their signatures, publish them to a registry, and install them as Claude Code skills (install-skill / skill-export).

The Problem This Solves

A plain skill is unsigned, unversioned, and locked to one tool — and LLMs cannot be relied upon to enforce security checks automatically.

Even with MCP server installed and protocol documentation:

• ❌ LLMs may skip verification
• ❌ No automatic enforcement mechanism
• ❌ Security depends on LLM "remembering" to check

This CLI provides: Mandatory verification enforced by code, not suggestions.

Installation

Option 1: NPM (Recommended)

Install globally:

npm install -g @ai-dossier/cli

Or use without installing:

npx @ai-dossier/cli <file-or-url>

Option 2: From Source (Development)

cd cli
npm link  # Links the CLI globally for development

# Or use directly
chmod +x bin/ai-dossier
./bin/ai-dossier verify <file-or-url>

Authentication

Interactive (Browser OAuth)

dossier login

Non-Interactive (CI/CD, Agents)

Set the DOSSIER_REGISTRY_TOKEN environment variable:

export DOSSIER_REGISTRY_TOKEN=<your-token>

# Optional: set user/org context
export DOSSIER_REGISTRY_USER=<username>
export DOSSIER_REGISTRY_ORGS=org1,org2

When DOSSIER_REGISTRY_TOKEN is set, it takes precedence over stored credentials. This is recommended for CI/CD pipelines, Docker containers, and AI agent contexts where interactive login is not possible.

Commands that require confirmation (publish, remove, cache clean) will fail with a clear error in non-interactive sessions. Use -y/--yes to skip confirmation prompts.

Usage

Basic Verification

# Verify local file
ai-dossier verify path/to/dossier.ds.md

# Verify remote dossier
ai-dossier verify https://example.com/dossier.ds.md

Exit codes:

• 0 - Verification passed (safe)
• 1 - Verification failed (unsafe)
• 2 - Error occurred

Verbose Mode

ai-dossier verify --verbose path/to/dossier.ds.md

Shows:

• Dossier metadata (title, version, risk level)
• Detailed checksum comparison
• Signature verification details
• Complete risk assessment

Integration with LLM Tools

Claude Code:

# Shell function wrapper
claude-run-dossier() {
  if ai-dossier verify "$1"; then
    claude-code "The dossier at $1 has been verified. Please execute it."
  else
    echo "❌ Security verification failed. Not executing."
  fi
}

# Use it
claude-run-dossier https://example.com/dossier.ds.md

Cursor:

cursor-run-dossier() {
  if ai-dossier verify "$1"; then
    cursor "Execute the verified dossier at $1"
  else
    echo "❌ Verification failed"
    return 1
  fi
}

Any LLM Tool:

safe-run-dossier() {
  local url="$1"
  local tool="${2:-claude-code}"

  if ai-dossier verify "$url"; then
    echo "✅ Dossier verified. Passing to $tool..."
    "$tool" "run $url"
  else
    echo "❌ Verification failed. Dossier not executed."
    return 1
  fi
}

# Usage
safe-run-dossier https://example.com/dossier.ds.md claude-code
safe-run-dossier https://example.com/dossier.ds.md cursor

Registry Commands

Search

Search for dossiers across all configured registries:

# Basic search
ai-dossier search "deployment"

# Filter by category
ai-dossier search "ci" --category devops

# Search dossier body content (-c is short for --content)
ai-dossier search "docker" -c

# Limit total results
ai-dossier search "setup" --limit 50

# Paginate results
ai-dossier search "setup" --page 2 --per-page 10

# JSON output
ai-dossier search "auth" --json

List

List dossiers from the registry, a local directory, or a GitHub repo:

# List all registry dossiers
ai-dossier list --source registry

# List with JSON output
ai-dossier list --source registry --json

# Paginate registry results
ai-dossier list --source registry --page 2 --per-page 10

# Filter by category (registry mode)
ai-dossier list --source registry --category security

# List local dossiers (-r is short for --recursive)
ai-dossier list .
ai-dossier list ./dossiers -r

# List from a GitHub repo
ai-dossier list github:owner/repo

# Filter local/GitHub results by risk level or signed status
ai-dossier list . --risk high
ai-dossier list . --signed-only

Pull

Download dossiers from the registry to the local cache (~/.dossier/cache/):

# Pull a dossier (latest version)
ai-dossier pull org/my-dossier

# Pull a specific version
ai-dossier pull org/[email protected]

# Pull multiple dossiers
ai-dossier pull org/dossier-a org/dossier-b

# Force re-download
ai-dossier pull org/my-dossier --force

Pulled dossiers are cached locally with checksum verification. Subsequent pull calls skip the download if the version is already cached (use --force to override). See Cache and Version Resolution for how versionless names are resolved and how to control freshness.

Export

Download a dossier and save it to a local file:

# Export to default filename (org-name.ds.md)
ai-dossier export org/my-dossier

# Export to a specific file
ai-dossier export org/my-dossier -o ./local-copy.ds.md

# Print to stdout (for piping)
ai-dossier export org/my-dossier --stdout

Skills

A dossier is a skill with trust, versioning, and registry distribution added. These commands bridge the registry and Claude Code skills (~/.claude/skills/).

A trigger skill is a thin SKILL.md that fires on a phrase and invokes a versioned, signed dossier via ai-dossier run <registry-path>. You author and trigger it like any skill, but it gains signing, version pinning, and registry distribution.

install-skill — registry dossier → Claude Code skill

# Install a published skill into ~/.claude/skills/
ai-dossier install-skill org/skills/my-skill

# List installed skills / force a fresh re-pull / remove one
ai-dossier install-skill --list
ai-dossier install-skill org/skills/my-skill --fresh --force
ai-dossier install-skill --remove my-skill

Restart Claude Code (or start a new session) to pick up a newly installed skill. At run time the skill calls ai-dossier run <registry-path>, which fetches and verifies the dossier on demand — so you don't need to install the dossier separately.

opencode support (auto-detect): When ~/.config/opencode/ exists, install-skill also writes a YAML-frontmatter wrapper to ~/.config/opencode/skills/<name>/SKILL.md. opencode's parser only accepts standard YAML frontmatter (---), so dossier skills that use ---dossier (JSON) frontmatter would otherwise be invisible. The wrapper carries the same name, description, and body; the signed source in ~/.claude/skills/ is never modified. Delegating skills (body contains ai-dossier run) also get an allowedTools: [Bash(ai-dossier run *)] line so opencode auto-approves the delegation.

Override with --for claude|opencode|both:

ai-dossier install-skill org/skills/my-skill --for claude   # skip opencode wrapper
ai-dossier install-skill org/skills/my-skill --for both     # force opencode even if dir absent

--remove cleans both locations. --list badges each skill with the tools it's installed in ([claude, opencode] or [claude]).

sync-skills — regenerate opencode wrappers for existing installs

Use after installing opencode on a machine that already has dossier skills, or after any manual change to ~/.claude/skills/:

ai-dossier sync-skills                # write missing wrappers, prune orphans
ai-dossier sync-skills --dry-run      # show what would change without writing
ai-dossier sync-skills --no-prune     # keep wrappers even if the source is gone
ai-dossier sync-skills --json         # machine-readable output

Idempotent — re-running is safe and reports unchanged for wrappers already in sync.

skill-export — local skill → registry dossier

Publish a locally installed skill to the registry as a versioned, signed dossier so others can install-skill it:

# Publish ~/.claude/skills/my-skill to the registry (minor version bump)
ai-dossier skill-export my-skill --namespace org/skills

# Pin an explicit version, add a changelog, verify the roundtrip
ai-dossier skill-export my-skill --version 2.0.0 --changelog "Add range support" --verify

| Option | Effect | |--------|--------| | --namespace <ns> | Registry namespace (default: first org or username) | | --version <v> / --major / --no-bump | Control the published version | | --changelog <msg> | Changelog message for the release | | --verify | Re-install after publish to confirm the roundtrip |

Runstate — workflow milestones

Issue-workflow dossiers (imboard-ai/git/full-cycle-issue and friends) record their progress by appending a <!-- runstate:v1 --> comment to the GitHub issue after every phase. That trail is the only run state that survives a session: it is what lets a later run resume mid-workflow instead of starting over.

Until now the milestone was a markdown heredoc that each agent reproduced by hand, and agents silently got it wrong — skipping milestones entirely, or pasting $(date …) into the comment verbatim. ai-dossier runstate makes it a command: the timestamp is filled in for you, and phase/status/required keys are validated before anything is posted.

# Mint the run id once, at the gate phase
ai-dossier runstate mint --issue 440            # -> r-440-ab56

# Post a milestone at the end of each phase
ai-dossier runstate post --issue 440 \
  --phase setup --status done --run r-440-ab56 \
  --kv branch=feature/440-runstate \
  --kv worktree=/repo/worktrees/feature-440-runstate \
  --kv pool_claimed=false \
  --kv base_branch=main

# Read the last milestone back
ai-dossier runstate last --issue 440 --json

# Ask where a run should resume from
ai-dossier runstate verify --issue 440

Subcommands

| Command | What it does | Writes? | |---|---|---| | post | Validates and posts one milestone comment via gh issue comment | yes | | last | Prints the most recent milestone on the issue, parsed | no | | verify | Runs the gate's resume verification and prints resume_from + resume_context | no | | mint | Prints a fresh run id (r-<issue>-<hex>) | no | | stats | Reports per-phase durations derived from the trail's at= stamps; aggregates across a --issues selection | no |

last, verify, and stats are strictly read-only — they only run gh issue view, gh pr view, git ls-remote/rev-parse, and stat, so they work fine without push access to the repository.

--issue <n> (a positive integer — the number only, not a URL or a #-prefixed string) is required by post, last, verify, and mint; stats takes either --issue <n> or --issues <list>, exactly one of the two. post, last, verify, and stats additionally take --repo <owner/name> (a bare slug, not a URL; defaults to the repository gh resolves for the current directory) and --json. mint takes --issue and nothing else.

last prints the milestone's own key=value lines, so the output is already in the shape a shell or a dossier reads:

$ ai-dossier runstate last --issue 440
phase=setup
status=done
run=r-440-ab56
at=2026-08-24T07:59:32Z
branch=feature/440-runstate
worktree=/repo/worktrees/feature-440-runstate
pool_claimed=false
base_branch=main
next=plan

With --json the same keys come back as one flat object; an issue with no milestones prints No runstate milestones on issue #440. (or null under --json) and exits 0.

post

| Flag | Meaning | |---|---| | --issue <n> | Issue to comment on (required) | | --phase <p> | gate, setup, plan, implement, review, ship, report (required) | | --status <s> | done, partial, blocked, awaiting-merge (required) | | --run <id> | Run id minted at the gate phase (required) | | --kv <key=value...> | Phase-specific key, repeatable (and variadic: --kv a=1 b=2 works too) | | --next <phase> | Override the computed next= line — a phase name or done | | --repo <owner/name> | Target repository (defaults to the current one) | | --dry-run | Print the comment body instead of posting it | | --json | Machine-readable output |

Validation failures print one actionable message per problem on stderr and exit 1 without posting:

$ ai-dossier runstate post --issue 440 --phase setup --status done --run r-440-ab56 --kv branch=x
❌ Phase 'setup' with status 'done' requires worktree= pool_claimed= base_branch= — add with --kv worktree=<value> --kv pool_claimed=<value> --kv base_branch=<value>

A valid --dry-run prints the exact body that would be posted:

$ ai-dossier runstate post --issue 440 --phase setup --status done --run r-440-ab56 \
    --kv branch=feature/440-runstate --kv worktree=/repo/worktrees/feature-440-runstate \
    --kv pool_claimed=false --kv base_branch=main --dry-run
<!-- runstate:v1 -->
phase=setup status=done run=r-440-ab56 at=2026-08-24T07:59:32Z
branch=feature/440-runstate
worktree=/repo/worktrees/feature-440-runstate
pool_claimed=false
base_branch=main
next=plan

Without --dry-run a successful post prints ✅ setup done → <comment url>; --json returns { "posted": true, "url": …, "body": … } (and { "posted": false, "dryRun": true, "body": … } under --dry-run). See When gh or git fails for what a failed post prints.

Phases, statuses, and required keys

This table is the executable copy of the "Runstate Milestones" table in imboard-ai/git/[email protected]:

| Phase | Statuses | Required keys | |---|---|---| | gate | done, blocked | base_branch warnings | | setup | done, blocked | branch worktree pool_claimed base_branch | | plan | done, blocked | planning head open_questions visual_review | | implement | done, blocked | head files tests_added tests_run ci_parity | | review | done, partial, blocked | head fixed escalated agents_done agents_pending | | ship (1st, before the CI wait) | awaiting-merge | pr head ci_fix_attempts | | ship (2nd, after merge + teardown) | done, blocked | pr merge_commit ci_fix_attempts cleanup | | report | done | pr traps_added |

A phase may carry keys beyond its required ones, and one is worth knowing about: gate should also pass model=<agent model id>, which is what lets runstate stats break whole-run durations down by model. Runs whose trail carries the key nowhere are bucketed as unknown.

The Statuses column is a closed set: a status not listed for a phase is rejected, so report cannot be blocked and only ship may be awaiting-merge. Any phase that can report status=blocked must also carry reason=<short-slug> when it does.

next= is computed for you: the linear order gate → setup → plan → implement → review → ship → report → done, except that blocked ends the run (next=done) and the two non-terminal statuses stay in their own phase — ship/awaiting-merge is followed by a second ship milestone, and a partial review still has agents to run. Use --next to override.

Key and value rules

Every --kv pair is checked before anything is posted:

• Keys are lower_snake_case (^[a-z][a-z0-9_]*$) and may appear at most once.
• No empty values — omit the key instead.
• No $ in values. This is the check that catches an unexpanded $(date …) before it reaches the issue.
• One line per value. A newline would split into extra key= lines that readers parse as real state, so it is rejected for every key, including ac* ones — collapse it (, or /) instead.
• No spaces in values (use - or ,). Only ac* keys — ac, ac1, ac_results — are exempt, because acceptance-criterion lines are prose. (The newline rule above still applies to them.)
• A value is at most 4000 characters and the whole comment at most 60000 (GitHub rejects a longer issue comment with an opaque 422). A milestone is an index, not a report: replace a long value with a count or a path to the full text.
• worktree= and planning= must be absolute paths, so a resume from a different working directory can still find them.
• --next must be a phase name or done. It is written to the comment verbatim, so an unchecked typo would point the next resume at a phase that does not exist.
• Comments are append-only: never edit or delete a prior milestone.

When gh or git fails

Every subcommand exits 1 on failure with the cause and its fix on stderr, so a calling dossier can branch on the exit code and an agent knows what to do next. The three causes that look identical from the outside are reported as three different things:

$ ai-dossier runstate last --issue 440
❌ Could not read issue #440: gh is not authenticated.
   Fix: run 'gh auth login', confirm with 'gh auth status', then re-run.
   gh said: To get started with GitHub CLI, please run:  gh auth login

| Cause | What you get | |---|---| | gh not on PATH | "'gh' is not installed, or is not on PATH" + the install link | | Not logged in | "gh is not authenticated" + gh auth login | | Issue/PR does not exist | "GitHub could not find it in …" + a nudge to check --repo | | No permission (403) | "the authenticated account lacks access to …" + gh auth status | | github.com unreachable | "gh could not reach GitHub" + retry guidance | | Anything else | the exit status, and "run the same gh command by hand" |

gh's own stderr is always echoed on a gh said: line, including for causes the CLI cannot classify — nothing is swallowed. gh exiting 0 with output that is not JSON, or with JSON that has no comments array, is also a hard failure rather than a silent "no milestones": the two must never look alike, because reading a fresh run out of a broken response makes a resume start over and throw away finished work.

When post cannot reach GitHub, it prints the exact gh issue comment … command to run by hand. The milestone is the only durable record of the phase, so re-running the phase costs far more than retrying the comment.

verify

verify implements imboard-ai/git/gate-issue's resume table. It never trusts the comment alone — each claim is checked against reality (is the branch still on the remote, does the worktree still exist, does the planning file exist, has HEAD moved, what is the PR's state) before it reports where to resume:

$ ai-dossier runstate verify --issue 440
resume_from=implement
run_id=r-440-ab56
verified=branch,worktree,planning
resume_context={"branch":"feature/440-runstate","worktree":"/repo/worktrees/feature-440-runstate",...}

resume_from is a phase name, or one of:

| Value | Meaning | |---|---| | none | No milestones on the issue — a fresh run | | ship-wait | The PR is open and mergeable; re-enter ship at the CI wait | | ship-teardown | The PR is already merged; re-enter ship at post-merge cleanup | | done | The report milestone is posted and the issue is closed (note=already complete) |

A failed check sends the resume backwards, never forwards: if the branch is gone from the remote or the worktree no longer exists, a plan/implement/review milestone still yields resume_from=setup. A milestone with status=blocked resumes at its own phase.

resume_context is merged across the run's milestones (later ones winning), so a resume at plan still sees branch/worktree from the setup milestone. (The dossier's own table carries only the last milestone's keys; merging is what makes a mid-run resume self-sufficient.) If the last three milestones are all blocked on the same phase, verify adds hard_block=resume-loop — the run is looping and needs a human.

When a check cannot run at all — git/gh is missing or the remote is unreachable, or the milestone's branch=/worktree=/pr= value is not one verify will hand to a subprocess — that check degrades to "not verified" and verify warns instead of failing. It still exits 0, because a conservative resume_from is the safe direction (redo a phase rather than skip one), but the reader needs to know the answer is conservative because a check could not run. Warnings go to stderr so stdout stays parseable:

⚠️  verify could not check everything: could not reach 'origin' to confirm branch 'feature/440-runstate' (git exited 128: fatal: 'origin' does not appear to be a git repository) — treating it as missing

Anyone who can comment on the issue can post a <!-- runstate:v1 --> body, so the values verify reads back are untrusted input. Nothing is run through a shell, and a value that would be read as a flag (leading -) or that is not the absolute path the protocol requires is refused rather than passed to git/gh — it becomes one of the warnings above.

--json returns the same fields as an object (resume_from, run_id, verified, resume_context, plus hard_block, note, and warnings when they apply).

stats

Every milestone stamps at=, so a run's per-phase durations are already in the trail — nothing has to be measured while the run happens. stats is the read side of that:

ai-dossier runstate stats --issue 440

Issue #440 — run r-440-ab56, model claude-opus-5 — total 49m 6s (2946s)
  phase       status          started               ended                       duration
  gate        done            -                     2026-08-24T07:42:54Z               -
  setup       done            2026-08-24T07:42:54Z  2026-08-24T07:45:11Z   2m 17s (137s)
  plan        done            2026-08-24T07:45:11Z  2026-08-24T07:47:08Z   1m 57s (117s)
  implement   done            2026-08-24T07:47:08Z  2026-08-24T07:55:05Z   7m 57s (477s)
  review      done            2026-08-24T07:55:05Z  2026-08-24T08:24:06Z  29m 1s (1741s)
  ship        awaiting-merge  2026-08-24T08:24:06Z  2026-08-24T08:25:39Z    1m 33s (93s)
  merge-wait  done            2026-08-24T08:25:39Z  2026-08-24T08:31:13Z   5m 34s (334s)
  report      done            2026-08-24T08:31:13Z  2026-08-24T08:32:00Z       47s (47s)

A phase starts at the previous milestone's at= and ends at its own, so the first milestone of a run has no measurable start and reports -. The gap between ship's two milestones is reported as its own merge-wait row: it is the one span that measures waiting rather than working, and folding it into ship would make ship's median a function of CI queue depth. A trail with several run= ids — a resumed or re-run issue — gets one table per run, never pairing one run's milestone with another's.

--issues takes a fleet-style selection (1,2,3, 1..9, or mixed 1,2,5..8, capped at 200 issues since each costs a gh call) and reports the aggregates instead of every table: per-phase median/min/max, a per-run total, and a breakdown by the model= the gate milestone recorded.

ai-dossier runstate stats --issues 440,448,451

Trails are imperfect in practice, and stats reports what it could not measure rather than guessing:

• A milestone whose at= is not a real timestamp — the literal $(date -u …) that pre-CLI heredocs pasted verbatim — is skipped and breaks the chain, so the next phase reports - instead of a duration silently covering two phases.
• A span that ends before it starts (milestones stamped by clocks that disagree) is reported as negative, and every aggregate row it lands in is marked ⚠ N skewed.
• A run with only one usable milestone — the normal state of anything still in flight — has no total, rather than a fabricated 0s that would drag every median toward zero.
• An issue with no runstate comments says so, and an issue that cannot be read at all is named and left out while the rest of the selection is still reported.

Warnings go to stderr in both human and --json mode, so stdout stays parseable and stats still exits 0 — a degraded read is not a failure. It exits 1 only when nothing in the selection could be read.

--json returns repo, issues, runs (each with run, model, last_phase, last_status, total_seconds, and a phases array of {phase, status, started_at, ended_at, seconds}), aggregates.phases, aggregates.models, issues_without_trail, issues_failed, and warnings.

Cache and Version Resolution

The CLI maintains a local cache at ~/.dossier/cache/:

• Content cache — ~/.dossier/cache/<name>/<version>.ds.md (the dossier bytes, content-addressable by version).
• Resolution cache — ~/.dossier/cache/.resolution/<name>.json (which version a versionless name resolves to, with TTL).

How versionless names resolve

Pinned references (org/[email protected]) are content-addressable and never expire — they bypass the resolver entirely.

Versionless references (org/my-dossier) are resolved through a TTL'd resolution cache:

1. If a recent resolution exists (within TTL) → reuse it (no registry call).
2. Otherwise → call the registry, write the resolved version to the resolution cache, return it.
3. If the registry is unreachable → fall back to the highest-semver cached version and print a loud stderr warning. If nothing is cached, fail with a clear error.

This applies to ai-dossier run, ai-dossier create, and ai-dossier install-skill.

Controlling freshness

| Flag | Effect | |------|--------| | (none) | Use cached resolution if newer than cache.resolutionTtlSeconds (default 300s). | | --max-age <seconds> | Override TTL for this call. 0 forces a registry check. | | --fresh | Skip the resolution cache and the content cache; fetch fresh from the registry. | | --pull (run only) | Refresh the content cache (re-download) but still resolve via the resolver. |

# Default: use cached resolution if within 300s
ai-dossier run org/my-dossier

# Force a registry re-check
ai-dossier run org/my-dossier --max-age 0

# Skip the entire cache for this call
ai-dossier run org/my-dossier --fresh

Configure the default TTL:

dossier config cache.resolutionTtlSeconds 600

cache subcommand

# Show all cached dossiers (content cache)
ai-dossier cache list
ai-dossier cache list --size --json

# Show cached versionless → version resolutions (with timestamps)
ai-dossier cache resolutions
ai-dossier cache resolutions --json

# Remove cached entries
ai-dossier cache clean <name>             # all versions of a dossier
ai-dossier cache clean <name> --ver 1.2.0 # specific version
ai-dossier cache clean --older-than 30    # entries older than N days
ai-dossier cache clean --all              # everything (prompts; use -y to skip)

Multi-Registry Resolution

The CLI queries all configured registries in parallel when resolving dossiers (e.g., dossier get, dossier run, dossier pull). This uses Promise.allSettled() so a single registry failure does not block results from other registries.

Exit Codes

Multi-registry commands use the following exit codes:

| Command | 0 (Success) | 1 (Failure) | 2 (Config/Runtime Error) | |---------|---------------|---------------|---------------------------| | get | Dossier found | Not found in any registry, or all registries failed | — | | list --source registry | Results returned, including when all registries fail (empty list + warnings) | Unexpected runtime error | — | | search | Results returned, including when all registries fail (no matches + warnings) | Unexpected runtime error | — | | pull | At least one item pulled successfully (per-item errors are printed as warnings) | All requested items failed to pull | — | | run | Dossier executed successfully | Not found, fetch failed, or verification failed | No LLM detected, unknown LLM, or execution failed |

Partial failures: When some registries fail but at least one succeeds, list returns exit 0 with a warning showing which registries failed:

⚠️  Registry 'internal': connection timeout
⚠️  Showing partial results (1/2 registries responded)

When all registries fail, list and search still exit 0 but display per-registry error warnings and report no results found.

No Registries Configured

If no registries are configured (no user config, no project .dossierrc.json, no DOSSIER_REGISTRY_URL env var), the CLI falls back to the hardcoded public registry (https://dossier-registry.vercel.app). Commands proceed normally — there is no error or special exit code for this scenario.

Error Handling

All multi-registry operations return structured errors alongside results:

$ dossier get org/my-dossier
# If registry A is down but registry B has it → returns result silently from B
# If no registry has it → displays errors from each registry

When all registries fail, the CLI displays per-registry error details showing which registry failed and why. When at least one registry succeeds, the result is returned without surfacing errors from other registries.

This means you can configure multiple registries for redundancy — the CLI will succeed as long as at least one registry can serve the requested dossier. Registries are queried in parallel; for get and run, the first successful result (by configuration order) is used.

Configuration

See dossier config for managing registry URLs. Multiple registries are queried in parallel, not sequentially.

Config Command

Manage CLI settings and registry configuration.

General Settings

# List all configuration
dossier config --list

# Get a setting
dossier config defaultLlm

# Set a setting
dossier config defaultLlm claude-code

# Reset to defaults (preserves registry settings)
dossier config --reset

Registry Management

All registry URLs must use HTTPS to protect credentials in transit.

# List configured registries
dossier config --list-registries
dossier config --list-registries --json

# Add a registry
dossier config --add-registry internal --url https://dossier.company.com

# Add as default + read-only
dossier config --add-registry mirror --url https://mirror.example.com --default --readonly

# Remove a registry
dossier config --remove-registry mirror

# Change the default registry
dossier config --set-default-registry internal

Project-Level Config (.dossierrc.json)

Place a .dossierrc.json in your project root for team-shared registry settings:

{
  "registries": {
    "internal": { "url": "https://dossier.company.com" }
  },
  "defaultRegistry": "internal"
}

Project registries are merged with user registries. User-configured registries take precedence on name conflicts to prevent credential exfiltration.

Environment Variables

| Variable | Description | |----------|-------------| | DOSSIER_REGISTRY_URL | Override/add a registry URL (creates virtual "env" registry) | | DOSSIER_REGISTRY_TOKEN | Auth token for the virtual "env" registry (ephemeral, never persisted to disk). Recommended for CI/CD and agent contexts. | | DOSSIER_REGISTRY_USER | Username for registry authentication | | DOSSIER_REGISTRY_ORGS | Comma-separated org scopes for registry queries |

What It Checks

1. Integrity (Checksum)

Verifies: Content hasn't been tampered with

How:

1. Extracts declared SHA256 hash from frontmatter
2. Calculates actual SHA256 of dossier body
3. Compares hashes

Result:

• ✅ Match → Content is intact
• ❌ Mismatch → Content has been modified → BLOCK

2. Authenticity (Signature)

Verifies: Dossier is from claimed author

How:

1. Checks if signature present in frontmatter
2. Validates signature format
3. Checks if key is in trusted keys list
4. Verifies signature against content

Result:

• ✅ Valid + Trusted → From known author
• ⚠️ Valid + Unknown → Signed but untrusted key
• ❌ Invalid → Signature failed → BLOCK
• ⚠️ No signature → Unsigned (warn for high-risk)

Managing trusted keys

Trust is a local decision: a valid signature from a key you have not added is reported as untrusted, never auto-trusted. Keys live in ~/.dossier/trusted-keys.txt, one <public-key> <identifier> per line.

ai-dossier keys generate --name my-key   # new Ed25519 pair in ~/.dossier/
ai-dossier keys list                     # what is trusted right now
ai-dossier keys add <public-key> <identifier>

keys add accepts a raw 44-char base64 key, an SPKI PEM block, or a legacy minisign RWT... key, and stores the canonical raw base64 form regardless — so a key added in one encoding still matches a signature carrying another. Anything it cannot interpret (a typo, a truncated key, a path to a .pub file) is rejected outright rather than written and silently never matching.

Passing a PEM needs --. A PEM begins with -, which the option parser reads as a flag:

ai-dossier keys add -- "$(cat ~/.dossier/my-key.pub)" "my-key"

ai-dossier verify <dossier> sidesteps this entirely — it prints a ready-to-run keys add command with the key already in base64 form.

If keys list warns about unusable entries, those keys are not trusted; the warning names the line to fix.

3. Risk Assessment

Analyzes:

• Dossier risk level (low/medium/high/critical)
• Presence of signature (required for high-risk)
• Checksum status
• Combined security posture

Outputs:

• Recommendation: ALLOW, WARN, or BLOCK
• Issue list
• Overall risk level

Examples

Example 1: Legitimate Dossier (Passes)

$ ai-dossier verify examples/data-science/train-ml-model.ds.md

🔐 Dossier Verification Tool

ℹ️  Reading: examples/data-science/train-ml-model.ds.md
✅ File read successfully
ℹ️  Parsing dossier...
✅ Parsed: Train ML Model v1.0.0

📊 Integrity Check:
✅ Checksum VALID - content has not been tampered with

🔏 Authenticity Check:
⚠️  No signature present (dossier is unsigned)

🔴 Risk Assessment:
   Risk Level: MEDIUM

Recommendation: ALLOW
✅ Safe to execute
   Dossier passed security verification.

$ echo $?
0

Example 2: Malicious Dossier (Blocked)

$ ai-dossier verify https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/security/validate-project-config.ds.md

🔐 Dossier Verification Tool

ℹ️  Downloading: https://...
✅ Downloaded successfully
ℹ️  Parsing dossier...
✅ Parsed: Validate Project Configuration v1.0.0

📊 Integrity Check:
❌ Checksum INVALID - content has been modified!

🔏 Authenticity Check:
⚠️  Signature verification failed (test signature)
   Signed by: DevTools Community <[email protected]>

🔴 Risk Assessment:
   Risk Level: CRITICAL

   Issues Found:
   - Checksum verification FAILED - content has been tampered with
   - Signature verification FAILED or could not be verified

Recommendation: BLOCK
❌ DO NOT EXECUTE this dossier
   Security verification failed.
   This dossier may have been tampered with or is from an untrusted source.

$ echo $?
1

Example 3: Shell Integration

# Add to ~/.bashrc or ~/.zshrc

# Wrapper function for Claude Code
claude-run-dossier() {
  echo "Verifying dossier security..."
  if ai-dossier verify "$1"; then
    echo ""
    echo "✅ Verification passed. Executing with Claude Code..."
    claude-code "Execute the verified dossier at $1"
  else
    echo ""
    echo "❌ Security verification failed."
    echo "   The dossier failed security checks and should not be executed."
    return 1
  fi
}

# Usage
claude-run-dossier https://example.com/dossier.ds.md

Registry Configuration

The CLI supports multiple registries for discovering, pulling, and publishing dossiers. Use dossier config to manage registries — see Config Command for CLI usage.

Configuration File (~/.dossier/config.json)

The CLI auto-creates ~/.dossier/config.json the first time you modify settings (e.g., via dossier config --add-registry). You do not need to create this file manually. If the file does not exist, the CLI uses built-in defaults (the public registry at https://dossier-registry.vercel.app).

{
  "registries": {
    "public": {
      "url": "https://dossier-registry.vercel.app",
      "default": true
    },
    "internal": {
      "url": "https://dossier.internal.example.com"
    },
    "readonly-mirror": {
      "url": "https://mirror.example.com",
      "readonly": true
    }
  },
  "defaultRegistry": "public"
}

See Read-Only Registries for how the "readonly" flag affects operations.

To create the config manually:

mkdir -p -m 700 ~/.dossier
cat > ~/.dossier/config.json << 'EOF'
{
  "registries": {
    "public": {
      "url": "https://dossier-registry.vercel.app",
      "default": true
    }
  }
}
EOF
chmod 600 ~/.dossier/config.json

Resolution Priority

1. --registry flag on the command
2. DOSSIER_REGISTRY_URL environment variable
3. Project-level .dossierrc.json
4. User-level ~/.dossier/config.json
5. Hardcoded default (public registry)

To verify which registries are active and their resolution order, run:

dossier config --list-registries

Read-Only Registries

Registries marked "readonly": true can be used for read operations (search, get, pull) but block write operations (publish, remove). Attempting a write operation against a read-only registry produces:

❌ Registry 'readonly-mirror' is read-only

When resolving a write target (e.g., for publish), the CLI skips read-only registries and falls back to the first writable registry. If all configured registries are read-only, the CLI returns:

❌ No writable registry configured. All registries are read-only.

Per-Command Registry Flag

Write commands accept --registry <name> to target a specific registry:

ai-dossier publish --registry team my-dossier.ds.md
ai-dossier login --registry internal

Read commands (search, get, pull) query all configured registries in parallel.

Agent Discovery (--agent)

The --agent flag outputs a machine-readable JSON manifest describing the CLI's capabilities. This is designed for AI agents that need to discover what the CLI can do programmatically:

ai-dossier --agent

Output includes:

• CLI version and available commands
• Supported flags (--json, -y/--yes)
• Capabilities (multi-registry, non-TTY safe, machine-readable errors)
• Discovery command for full command listing

This enables agents to auto-configure their integration with the Dossier CLI without parsing help text.

Architecture

How It Works

User Command:
ai-dossier verify https://example.com/dossier.ds.md
         ↓
    Download/Read File
         ↓
    Parse Frontmatter
    (Extract metadata)
         ↓
    Calculate SHA256
    (Dossier body only)
         ↓
    Compare Hashes
    ┌────────┴────────┐
    ↓                 ↓
MATCH              MISMATCH
    ↓                 ↓
Check Signature    BLOCK (exit 1)
    ↓
Assess Risk
    ↓
Exit 0 (safe) or 1 (unsafe)

Design Principles

1. Fail Secure: Default to blocking on any verification failure
2. Exit Codes: Machine-readable results for scripting
3. Clear Output: Human-readable for manual use
4. Minimal Dependencies: Core verification + commander CLI framework
5. Fast: Verification in milliseconds

Capabilities & Limitations

What's implemented

• ✅ Checksum verification (SHA256) — catches any tampering with the dossier body
• ✅ Signature verification — Ed25519 (Minisign-compatible) and AWS KMS; signatures are validated, not just detected
• ✅ Trusted keys — verified against ~/.dossier/trusted-keys.txt; manage with ai-dossier keys
• ✅ Risk assessment — declared risk level + destructive-operation analysis gate execution
• ✅ Execution — ai-dossier run verifies, then executes if checks pass

Current limitations

• Verification is a single integrity stage (checksum + signature) plus risk assessment — there is no multi-stage sandbox; the executing agent enforces runtime permissions.
• Trust is local: you decide which keys to trust. A valid signature from an untrusted key is reported as such, not auto-trusted.

Roadmap

v0.1.0

• ✅ Basic checksum verification
• ✅ Signature presence detection
• ✅ Exit code support
• ✅ URL download support

v0.2.0

• ✅ Multi-command CLI structure (ai-dossier <command>)
• ✅ ai-dossier run command with integrity verification (checksum + signature)
• ✅ LLM auto-detection and execution integration

v0.3.0

• ✅ Modular TypeScript migration
• ✅ Comprehensive test suite (261+ tests)
• ✅ CLI parity with dossier-tools
• ✅ @ai-dossier npm scope and CI/CD publishing

v0.4.0

• ✅ Unified dossier parser across core/cli/mcp
• ✅ JSON output mode (--json flag on commands)
• ✅ Registry integration (publish, remove, install-skill)
• ✅ Non-TTY stdin detection

v0.5.0

• ✅ Multi-registry support with parallel resolution
• ✅ dossier create command with meta-dossier templates
• ✅ dossier export and dossier pull commands
• ✅ Agent discovery (--agent flag)
• ✅ Enhanced auth: browser OAuth and env-based tokens

v0.6.0

• ✅ Unified dossier+skill creation template
• ✅ Pool-aware setup-issue-workflow dossiers
• ✅ @ai-dossier/worktree-pool package

v0.7.0

• ✅ Security hardening (execFileSync, Zod validation)
• ✅ Node 20+ requirement
• ✅ Coverage thresholds enforcement
• ✅ Documentation consistency fixes

v0.8.x (Current)

• ✅ Zod validation on MCP prompt handlers
• ✅ Complete doc link audit and fix (30+ broken links)
• ✅ Ed25519 + AWS KMS signature verification with trusted-keys
• ✅ install-skill / skill-export (Claude Code skill bridge)
• ✅ Execution tracing with verified checksum + signer metadata
• ✅ TTL-based version resolution for the content cache

v1.0.0 (Stable)

• ⏳ Stable, frozen CLI surface and exit-code contract
• ⏳ Deeper integration with major LLM tools
• ⏳ Expanded registry/discovery features

Contributing

Development Setup

cd cli
npm link  # For local testing

# Test
ai-dossier verify ../examples/devops/deploy-to-aws.ds.md

# Test with malicious example
ai-dossier verify ../examples/security/validate-project-config.ds.md

Adding Features

Priority areas:

1. Full minisign signature verification
2. Trusted keys management
3. --run flag implementation
4. Integration examples for more tools

See: CONTRIBUTING.md

Troubleshooting

"insecure permissions" warning

⚠️  Warning: ~/.dossier/credentials.json has insecure permissions (644). Expected 0600. Credentials may have been compromised. Fixing permissions.

What it means: The credentials file is readable by other users on the system. The CLI expects 0600 (owner read/write only) to protect your authentication tokens.

How to fix:

chmod 600 ~/.dossier/credentials.json

The CLI will also attempt to fix permissions automatically when it detects this issue.

Common causes:

• Manually creating or editing the file with a text editor
• Copying the file from another system without preserving permissions
• Running the CLI as a different user than the file owner

"Failed to save credentials"

Failed to save credentials to ~/.dossier/credentials.json: <reason>

What it means: The CLI could not write to the credentials file after dossier login or a token refresh.

How to fix:

1. Check directory exists: The config directory ~/.dossier/ must exist. The CLI creates it automatically, but if creation failed:

   mkdir -p ~/.dossier
   chmod 700 ~/.dossier

2. Check write permissions: Ensure your user owns the directory and file:

   ls -la ~/.dossier/
   # If ownership is wrong:
   sudo chown -R $(whoami) ~/.dossier

3. Check disk space: Ensure the filesystem has available space.

4. Check for read-only filesystem: In some container or CI environments, the home directory may be read-only. Use the DOSSIER_REGISTRY_TOKEN environment variable instead:

   export DOSSIER_REGISTRY_TOKEN=<your-token>

"Registry not found"

Registry 'myregistry' not found. Available: public. Run 'dossier config --list-registries' to see configured registries.

What it means: The --registry flag references a registry name that isn't configured.

How to fix:

1. List configured registries to see what's available:

   dossier config --list-registries

2. Add the missing registry:

   dossier config --add-registry myregistry --url https://dossier.example.com

"Unreachable registry URL"

When a registry is unreachable, the error appears as part of per-registry error output:

❌ Not found in any registry: org/my-dossier
   internal: fetch failed

What it means: The registry URL is not reachable — the server may be down, the URL may be wrong, or there may be a network/firewall issue. When using multiple registries, the CLI succeeds as long as at least one registry responds (see Multi-Registry Resolution).

How to fix:

1. Verify the URL is correct:

   dossier config --list-registries
   curl -s https://dossier.company.com/health

2. If the URL is wrong, remove and re-add:

   dossier config --remove-registry internal
   dossier config --add-registry internal --url https://correct-url.company.com

"Malformed config file"

⚠️  Warning: Could not read config file (Unexpected token ...), using defaults

What it means: The config file contains invalid JSON. The CLI does not fail — it logs a warning and falls back to built-in defaults.

How to fix:

1. Validate the JSON:

   python3 -m json.tool < ~/.dossier/config.json

2. Fix syntax errors, or delete and recreate:

   rm ~/.dossier/config.json
   dossier config --add-registry public --url https://dossier-registry.vercel.app --default

FAQ

Q: Why a separate CLI tool?

A: Security cannot be enforced through LLM instructions alone. We need code-level enforcement that runs before LLMs get involved.

Q: Does this replace MCP server?

A: No, they're complementary:

• CLI: Enforcement layer (verify before execution)
• MCP server: Convenience layer (tools for LLMs)

Use both for best results.

Q: Can I use this with any LLM tool?

A: Yes! The CLI is tool-agnostic. Create a wrapper function for your specific tool.

Q: What if I don't want to install it?

A: Use the verification script from SECURITY_STATUS.md or manually verify checksums.

Support

Issues: https://github.com/imboard-ai/ai-dossier/issues Security: [email protected] Discussions: https://github.com/imboard-ai/ai-dossier/discussions

Remember: Security is enforced by code, not suggestions. Use this tool to guarantee verification happens.