>_ ankicli

Docs

Troubleshooting

When ankicli fails, start by validating the runtime, backend support, and profile resolution instead of guessing which layer broke.

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

  • Install completed but commands still fail.
  • An agent reports backend unavailable, runtime mismatch, or profile resolution errors.

What the agent should know

  • Start with `doctor env` and `doctor backend` before retrying mutations.
  • Treat structured ankicli errors as real signals. Do not collapse them into vague summaries.

Check the environment first

These commands surface runtime health, default Anki roots, backend support, and capability gaps.

Diagnostic baseline

ankicli --json doctor env
ankicli --json doctor backend
ankicli --json doctor capabilities

If install or startup fails

A healthy install still needs a healthy runtime. If the binary launches but commands fail, start with the doctor commands before retrying the installer.

  • If the command is not found, fix PATH before debugging the backend.
  • If `doctor backend` reports unsupported runtime, treat that as a runtime or setup problem, not a collection problem.

Install troubleshooting

ankicli --version
ankicli --json doctor env
ankicli --json doctor backend

Check profile resolution and target selection

If a collection command fails, confirm the selected profile or collection path before blaming the backend.

Profile troubleshooting

ankicli --json profile list
ankicli --json profile resolve --name "User 1"
ankicli --json --profile "User 1" collection info

Check auth and sync separately

If sync behavior is wrong, separate credential problems from collection problems. Start with auth status and sync status before a real sync run.

  • Treat sync as coordination, not backup.
  • Create a backup before retrying a risky sync path after a failure.

Auth and sync troubleshooting

ankicli --json auth status
ankicli --json --profile "User 1" sync status
ankicli --json --profile "User 1" backup create

Common failure modes

Most failures cluster around runtime health, credential state, or target selection.

  • If runtime support is false, inspect the bundled runtime version and failure reason from `doctor backend`.
  • If auth fails, check `auth status` before retrying sync commands.
  • If a mutation is blocked, try `--dry-run` first and verify the target with a read command.