Docs

Profiles and collections

Use profiles for the normal human path and explicit collection paths when you need deterministic low-level targeting for automation or troubleshooting.

Copy this guide

Paste it into Claude, Codex, or OpenClaw for structured context.

Paste this page into your LLM chat for structured context.

When to use this

You want to point ankicli at the correct local Anki data without guessing where the collection lives.
You need to choose between --profile and --collection in a script or agent workflow.

What the agent should know

Use saved ankicli workspaces for ordinary local-user flows. Use --collection only when exact file targeting matters.
Profile resolution is platform-aware and is safer than hard-coding Anki paths when the operator has a normal local setup.

Use profiles by default

For most humans, profile-aware commands are the best fit because they map cleanly to the Anki app’s own data model.

Profile inspection

ankicli --json profile list
ankicli --json profile default
ankicli --json profile resolve --name "User 1"
ankicli workspace set --profile "User 1"
ankicli workspace set --name travel --profile "Travel"
ankicli --json workspace list

Use collection paths when you need exactness

Use explicit collection paths when debugging, testing, or automating against a known file path rather than a named Anki profile.

Collection-targeted inspection

ankicli workspace set --collection /path/to/collection.anki2
ankicli --json collection info
ankicli --json deck stats --name Default

Troubleshooting hints

If a profile does not resolve, inspect the profile list and the resolved data root before assuming the collection is missing.

Human-facing workspace config lives under `~/.ankicli/workspaces/<name>/config.json`.
Run `ankicli --json doctor env` to inspect the default Anki root.
Run `ankicli --json workspace path` to inspect the saved workspace location.
Run `ankicli --json workspace list` to inspect named workspaces.
Use `profile list` before hard-coding a collection path.