>_ ankicli

Operations

CLI guide

Use this page when you need the practical shape of ankicli commands: how targeting works, when to use --json, and which safety flags matter before real collection mutations.

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 a fast mental model for how ankicli commands are structured.
  • You need exact command patterns for scripts, agent harnesses, or manual terminal use.

What the agent should know

  • Use `--json` by default in automation contexts.
  • Pick one target mode first: `--profile` for normal local use or `--collection` for exact file targeting.

Start with help output

The fastest way to discover the live CLI surface is still the built-in help. Use top-level help first, then narrow into the subcommand group you actually need.

Help discovery

ankicli --help
ankicli profile --help
ankicli search --help
ankicli note --help
ankicli backup --help
ankicli sync --help
ankicli study --help

Understand the command shape

Most real commands follow the same pattern: global output and target flags first, then the subcommand group, then the concrete action and its arguments.

That consistency matters because it makes the CLI easier for humans to scan and easier for agents to generate reliably.

Typical command shape

ankicli --json --profile "User 1" collection info
ankicli --json --profile "User 1" search preview --kind notes --query 'deck:Default'
ankicli --json --profile "User 1" note update --id 123 --field Back="Updated text"

Choose the right target mode

Use `--profile` when the operator has a normal local Anki setup and wants ankicli to resolve the right collection automatically.

Use `--collection` when you need to hit an exact file path for debugging, test fixtures, or tightly controlled automation.

  • Prefer `--profile` for ordinary human and operator flows.
  • Prefer `--collection` only when exact file targeting is part of the requirement.

Targeting examples

ankicli --json --profile "User 1" collection info
ankicli --json --collection /path/to/collection.anki2 collection info

Use the safety flags intentionally

`--dry-run` is the default way to preview a risky mutation. `--yes` is the explicit confirmation for destructive or sensitive operations that should not happen by accident.

  • Use read commands first when the target is not fully obvious.
  • Let the human supervise the final write step when the operation is broad or destructive.

Safety patterns

ankicli --json --profile "User 1" note add-tags --id 123 --tag review --dry-run
ankicli --json --profile "User 1" card suspend --id 456 --yes