zoxide CLI

CuratedAudited 2026-10-28 by anc 0.7.0Markdown · JSON
72pass rate

2/8 principles met

A smarter cd command

$ anc audit zoxide --json

workhorse Rust ajeetdsouza/zoxide
MUST 19 / 28SHOULD 14 / 221 failing14 warningsaudited 2026-10-28 · anc 0.7.0

Eight principles, scored

Behavioral and source checks. Every non-pass row carries a copy-paste remediation prompt.

  1. P1
    Non-Interactive by Default

    no default-value annotations found in --help. SHOULD-tier — agents reading help text need to see what value a flag falls back to when omitted (`[default: <value>]` per clap convention). · no rich-TUI affordance detected (no `--tui`/`--interactive`/`--ui` flag, no spinner/progress/tui mention in --help). MAY-tier — rich TUI in TTY contexts is a nice-to-have, not required.

    Remediation · P1
    Make zoxide satisfy P1 (Non-Interactive by Default) from the agent-native CLI standard. Address:
    - `--help` advertises default values for flags (no default-value annotations found in --help. SHOULD-tier — agents reading help text need to see what value a flag falls back to when omitted (`[default: <value>]` per clap convention).)
    - Rich-TUI affordance for TTY contexts (no rich-TUI affordance detected (no `--tui`/`--interactive`/`--ui` flag, no spinner/progress/tui mention in --help). MAY-tier — rich TUI in TTY contexts is a nice-to-have, not required.)
    Requirements: https://anc.dev/p1
    warn
  2. P2
    Structured, Parseable Output

    no --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum. · no `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.

    Remediation · P2
    Make zoxide satisfy P2 (Structured, Parseable Output) from the agent-native CLI standard. Address:
    - --json / --jsonl short aliases for --output (no --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum.)
    - `--raw` flag for pipe-safe unformatted output (no `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.)
    Requirements: https://anc.dev/p2
    warn
  3. P3
    Progressive Help Discovery

    no `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text. · `-h` and `--help` produce byte-identical output. SHOULD-tier — clap renders the short summary on `-h` and the full description on `--help` when `long_about` is set; collapsing them gives agents no concise list-level grep target.

    Remediation · P3
    Make zoxide satisfy P3 (Progressive Help Discovery) from the agent-native CLI standard. Address:
    - `examples` subcommand or `--examples` flag for curated usage patterns (no `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text.)
    - Short `-h` summary differs from `--help` long form (`-h` and `--help` produce byte-identical output. SHOULD-tier — clap renders the short summary on `-h` and the full description on `--help` when `long_about` is set; collapsing them gives agents no concise list-level grep target.)
    - Help text pairs human and `--output json` example invocations (no paired text + `--output json` example found within 5 lines in top-level or any subcommand `--help`. Pairing keeps agents from reverse-engineering the JSON invocation from the text one.)
    Requirements: https://anc.dev/p3
    warn
  4. P4pass
  5. P5
    Safe Retries & Mutation Boundaries

    destructive subcommand(s) whose --help lists no confirmation flag: remove. Accepted flags: --force, --yes, -y, -f, --auto-approve, --assume-yes, --confirm. Irreversible operations must require explicit confirmation so they can't be invoked accidentally.

    Remediation · P5
    Make zoxide satisfy P5 (Safe Retries & Mutation Boundaries) from the agent-native CLI standard. Address:
    - Destructive subcommands require `--force` or `--yes` (destructive subcommand(s) whose --help lists no confirmation flag: remove. Accepted flags: --force, --yes, -y, -f, --auto-approve, --assume-yes, --confirm. Irreversible operations must require explicit confirmation so they can't be invoked accidentally.)
    Requirements: https://anc.dev/p5
    fail
  6. P6
    Composable, Predictable Command Structure

    3/6 subcommand(s) follow standard verb names. Non-standard: edit, import, query. MAY-tier — community-standard verbs (get/list/create/update/delete) help agents predict subcommand behavior across CLIs. · no `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.

    Remediation · P6
    Make zoxide satisfy P6 (Composable, Predictable Command Structure) from the agent-native CLI standard. Address:
    - Subcommand verbs follow community-standard names (3/6 subcommand(s) follow standard verb names. Non-standard: edit, import, query. MAY-tier — community-standard verbs (get/list/create/update/delete) help agents predict subcommand behavior across CLIs.)
    - `--color` flag for explicit color control (no `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.)
    Requirements: https://anc.dev/p6
    warn
  7. P7
    Bounded, High-Signal Responses

    no option definition in --help declares --quiet or -q; a flag named only in a usage line does not count. · no `--verbose` / `-v` flag advertised. SHOULD-tier — agents debugging failures need a way to escalate diagnostic detail.

    Remediation · P7
    Make zoxide satisfy P7 (Bounded, High-Signal Responses) from the agent-native CLI standard. Address:
    - Quiet mode available (no option definition in --help declares --quiet or -q; a flag named only in a usage line does not count.)
    - `--verbose` flag for diagnostic escalation (no `--verbose` / `-v` flag advertised. SHOULD-tier — agents debugging failures need a way to escalate diagnostic detail.)
    - `--limit` / `--max-results` flag for list operations (list-style subcommand(s) with no limit flag in their --help: query (looked for --limit, --max-results, --max, --top, or a -n that bounds a count). SHOULD-tier: callers should be able to bound response size directly rather than scrape-then-truncate.)
    - Cursor-based pagination flags for list traversal (no list-style subcommand advertises a cursor/page flag in its --help: query (looked for --after, --before, --cursor, --page, --offset). MAY-tier: cursor pagination lets agents traverse large result sets without re-scanning earlier pages.)
    - Help text advertises TTY-aware verbosity behavior (no TTY-aware language found in `--help`. MAY-tier — automatic verbosity reduction when stdout is piped or redirected lets agents skip the explicit `--quiet` flag. Behavioral probes cannot simulate a real TTY without a pty crate, so this audit relies on documented intent.)
    Requirements: https://anc.dev/p7
    warn
  8. P8pass

All Audits

P1: Non-Interactive by Default

PASSNon-interactive by default
SKIPNon-interactive gate flag advertised in --helptarget satisfies P1 via alternative gate (help-on-bare or stdin-primary)
PASSFlags advertise env-var bindings in --help
PASSSecret-bearing flags expose stdin or *-file companion
WARN`--help` advertises default values for flagsno default-value annotations found in --help. SHOULD-tier — agents reading help text need to see what value a flag falls back to when omitted (`[default: <value>]` per clap convention).
WARNRich-TUI affordance for TTY contextsno rich-TUI affordance detected (no `--tui`/`--interactive`/`--ui` flag, no spinner/progress/tui mention in --help). MAY-tier — rich TUI in TTY contexts is a nice-to-have, not required.

P2: Structured, Parseable Output

OPT-OUTStructured output supportno option definition in --help, or in the --help of the 6 subcommands read, declares --output, --format, --output-format, --json or --jsonl, the flags this requirement accepts; a flag named only in a usage line does not count.
N/AStructured-output CLI exposes its schema at runtimeantecedent `p2-json-output` is opt_out: no option definition in --help, or in the --help of the 6 subcommands read, declares --output, --format, --output-format, --json or --jsonl, the flags this requirement accepts; a flag named only in a usage line does not count.
WARN--json / --jsonl short aliases for --outputno --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum.
WARN`--raw` flag for pipe-safe unformatted outputno `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.
SKIP`--output` advertises additional formats beyond text/jsonno `--output` or `--format` flag advertised; vacuous skip for MAY-tier extra formats.
PASSBad invocation exits with structured usage-error code (2)
SKIPErrors emit JSON envelope with discriminant + type id + message roles under `--output json`no option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); MUST applies only to CLIs that opt into the JSON contract.
SKIPJSON success and error envelopes share their non-payload key setno option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); envelope-consistency only applies to CLIs that opt into the JSON contract.

P3: Progressive Help Discovery

PASSHelp flag produces useful output
PASSVersion flag works (`--version` plus short alias)
PASSVersion flag works (`--version` plus short alias)
WARN`examples` subcommand or `--examples` flag for curated usage patternsno `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text.
WARNShort `-h` summary differs from `--help` long form`-h` and `--help` produce byte-identical output. SHOULD-tier — clap renders the short summary on `-h` and the full description on `--help` when `long_about` is set; collapsing them gives agents no concise list-level grep target.
PASSEach subcommand that takes arguments ships an invocation example in its `--help`
WARNHelp text pairs human and `--output json` example invocationsno paired text + `--output json` example found within 5 lines in top-level or any subcommand `--help`. Pairing keeps agents from reverse-engineering the JSON invocation from the text one.
PASSCommand-list entries name the command without repeating the binary name

P4: Fail-Fast, Actionable Errors

PASSRejects invalid arguments
PASSError messages include a hint or remediation phrase
SKIP`--output json` produces JSON-formatted errorsno option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); SHOULD applies only to CLIs that opt into the JSON contract.

P5: Safe Retries & Mutation Boundaries

FAILDestructive subcommands require `--force` or `--yes`destructive subcommand(s) whose --help lists no confirmation flag: remove. Accepted flags: --force, --yes, -y, -f, --auto-approve, --assume-yes, --confirm. Irreversible operations must require explicit confirmation so they can't be invoked accidentally.
PASSRead and write surfaces are both visible in subcommand list

P6: Composable, Predictable Command Structure

PASSHandles SIGPIPE gracefully
SKIPPager-using CLI ships --no-pager escape hatchno pager signal ($PAGER, --pager, pager, or less/more named as a program) in --help
PASSRespects NO_COLOR
WARNSubcommand verbs follow community-standard names3/6 subcommand(s) follow standard verb names. Non-standard: edit, import, query. MAY-tier — community-standard verbs (get/list/create/update/delete) help agents predict subcommand behavior across CLIs.
WARN`--color` flag for explicit color controlno `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.
SKIPInput-accepting commands read from stdin when no file is givenno input-accepting subcommand detected (process/parse/convert/transform/analyze/validate/format/lint/audit); vacuous skip for the conditional SHOULD.
PASSSubcommand naming follows a consistent verb/noun convention
PASSOperations are subcommands, not verb-shaped flags

P7: Bounded, High-Signal Responses

WARNQuiet mode availableno option definition in --help declares --quiet or -q; a flag named only in a usage line does not count.
WARN`--verbose` flag for diagnostic escalationno `--verbose` / `-v` flag advertised. SHOULD-tier — agents debugging failures need a way to escalate diagnostic detail.
WARN`--limit` / `--max-results` flag for list operationslist-style subcommand(s) with no limit flag in their --help: query (looked for --limit, --max-results, --max, --top, or a -n that bounds a count). SHOULD-tier: callers should be able to bound response size directly rather than scrape-then-truncate.
WARNCursor-based pagination flags for list traversalno list-style subcommand advertises a cursor/page flag in its --help: query (looked for --after, --before, --cursor, --page, --offset). MAY-tier: cursor pagination lets agents traverse large result sets without re-scanning earlier pages.
SKIP`--timeout` flag for long-running operationsno long-running subcommand detected (serve/daemon/watch/tail/monitor/follow/run/start/stream); vacuous skip for the conditional SHOULD.
WARNHelp text advertises TTY-aware verbosity behaviorno TTY-aware language found in `--help`. MAY-tier — automatic verbosity reduction when stdout is piped or redirected lets agents skip the explicit `--quiet` flag. Behavioral probes cannot simulate a real TTY without a pty crate, so this audit relies on documented intent.

P8: Discoverable Through Agent Skill Bundles

N/ASkill bundle has install path (`tool skill install [<host>]`)no skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand
N/A`skill install --all` for multi-runtime installno skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand
N/A`skill update` / `skill upgrade` for bundle refreshno skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand

Details

Version scored
0.10.0
Audit date
2026-10-28 15:54:12 UTC
Duration
135ms
Platform
linux/x86_64
Mode
command
Anc build
0.7.0
Install
brew install zoxide

Embed the badge

This score (72%) clears the badge floor (70%). Copy this into your README:

[![agent-native](https://anc.dev/badge/zoxide.svg)](https://anc.dev/score/zoxide)

Preview: agent-native badge for zoxide

Reproduce this scorecard for zoxide locally and inspect the failing audits:

anc audit --command zoxide --output json

Install anc first if you don't have it. Add --output json to get the same JSON shape committed under scorecards/.