Installation & Configuration

How to install the Dossier tooling and configure registries and authentication.

Just want to run a dossier? See the Quick Start — you don’t need to install anything for the zero-install path.

Install the CLI

# Install globally (provides the `ai-dossier` command)
npm install -g @ai-dossier/cli

# Or run without installing
npx @ai-dossier/cli verify <dossier-file-or-url>

Requires Node.js 20+.

Standalone binary (no Node.js)

Prebuilt single-file executables for Linux (x64, arm64), macOS (x64, arm64) and Windows (x64) are attached to each cli-v<version> GitHub Release together with a SHA256SUMS file.

curl -fsSL https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/install.sh | sh
# pin a version / choose the directory:
curl -fsSL https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/install.sh | sh -s -- --version X.Y.Z --dir /usr/local/bin

The script detects your OS and CPU, downloads the binary, verifies its SHA256 against SHA256SUMS, and installs it to ~/.local/bin (or --dir / $AI_DOSSIER_INSTALL_DIR). On Windows, download ai-dossier-win32-x64.exe from the release page (or run the script from Git Bash) and verify it with certutil -hashfile ai-dossier-win32-x64.exe SHA256.

macOS Gatekeeper. The binaries are ad-hoc signed but not notarized. Downloaded through install.sh (curl) they run without a prompt; downloaded through a browser, macOS quarantines them and reports the app cannot be verified. Clear it with xattr -d com.apple.quarantine ./ai-dossier-darwin-arm64 (or right-click, Open). Windows SmartScreen may warn on first run of the unsigned .exe: choose “More info”, then “Run anyway”.

The binary is a Node Single Executable Application (the Node runtime plus the bundled CLI, roughly 120 MB), built by node scripts/build-sea.mjs (make build-binary). Behaviour is identical to the npm install.

Add the MCP server (Claude Code)

One command gives Claude Code native dossier support — discover, verify, and run dossiers in conversation:

claude mcp add dossier --scope user -- npx @ai-dossier/mcp-server

Alternatives (plugin with auto-updates, or manual JSON config for Claude Desktop / other MCP clients) are in the MCP server README. For the trigger-skill route (install dossiers as Claude Code skills), see Using Dossier with Claude Code.

Authentication

Authentication is only needed to publish to, or pull private dossiers from, a registry.

# Interactive login (opens browser)
ai-dossier login

# Non-interactive (CI/CD, agents)
export DOSSIER_REGISTRY_TOKEN=<your-token>

Authentication troubleshooting

For CI/CD, always use the environment variable:

export DOSSIER_REGISTRY_TOKEN="${DOSSIER_TOKEN}"   # from your CI secrets
ai-dossier publish my-dossier.ds.md

Registry configuration

By default the CLI uses the public Dossier registry (https://dossier-registry.vercel.app). Teams can add registries in ~/.dossier/config.json:

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

Or per-project via .dossierrc.json in your project root (good for team-shared settings):

{
  "registries": {
    "team": { "url": "https://dossier.myteam.example.com" }
  },
  "defaultRegistry": "team"
}

Authenticate per registry:

ai-dossier login                      # default registry
ai-dossier login --registry internal  # named registry

Viewing configured registries

# Human-readable
ai-dossier config --list-registries

# Machine-readable JSON (for scripts and agents)
ai-dossier config --list-registries --json

If an error says a registry was not found, run --list-registries to verify the name. See the CLI README for full details.

Credential troubleshooting

“insecure permissions” warning

The CLI stores tokens in ~/.dossier/credentials.json with 0600 permissions. If loosened, you’ll see a warning; fix with:

chmod 600 ~/.dossier/credentials.json

The CLI also attempts to fix this automatically.

“Failed to save credentials”

The CLI couldn’t write the credentials file after login:

1. Ensure ~/.dossier/ exists and is writable:

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

2. In containers/CI with a read-only home, use a token instead:

   export DOSSIER_REGISTRY_TOKEN=<your-token>

See the CLI README troubleshooting for more.

Next steps

• Quick Start — run your first dossier
• Author your first dossier
• Using Dossier with Claude Code — MCP and trigger skills
• FAQ — common questions and comparisons

Rendered from docs/getting-started/installation.md in the repository. Edit it there.