cli reference

Complete reference for the crate-seq command-line interface. Written for Rust developers publishing crates to the registry.

Synopsis

crate-seq [--no-color] <COMMAND>

Global flags

---

Commands

init

Initialises ledgers from git tags and crates.io state. Walks to the repository root, discovers workspace members (or a single crate), writes .crate-seq.toml ledger files, and prints each crate name with its version count.

crate-seq init [--crate <NAME>] [--path <DIR>]

Behaviour:

• Discovers workspace members, queries crates.io for existing versions, and writes .crate-seq.toml ledger files
• Prints each initialized crate name in green with its version count

Example output:

my-crate: 5 versions
my-other-crate: 3 versions

Errors: Propagates workspace discovery errors, registry errors, and ledger write failures.

---

check

Diffs local pending versions against crates.io state. For each crate, displays pending, skipped, and orphaned entries.

crate-seq check [--crate <NAME>] [--path <DIR>]

Output format:

• Up to date — crate name in green with "up to date" and the registry latest version
• Pending — versions in yellow with their git ref
• Skipped — versions in dim text
• Orphaned — versions in red with "ref missing" (the git tag referenced by the ledger entry no longer exists)

Example output:

my-crate @ 0.2.0 — up to date
my-other-crate @ 0.1.0 (registry latest)
  pending:  0.2.0 (my-other-crate-v0.2.0)
  orphaned: 0.1.5 <- ref missing

Errors: Returns early with a message if no ledger files are found ("No ledger files found. Run crate-seq init first."). Propagates check_crate errors.

---

publish

Publishes pending versions to crates.io. Dry-run by default — pass --execute for live publishing.

crate-seq publish [--execute] [--token <TOKEN>] [--crate <NAME>] [--path <DIR>]

Dry-run mode (default)

Iterates each ledger and calls crate_seq_core::publish_dry_run(). For each pending version, reports one of:

• ok — version is ready to publish
• FAIL — package failed — cargo package failed (first 5 lines of stderr shown)
• FAIL — path deps found — unresolved path dependencies detected
• FAIL — cargo check failed — compilation errors (first 5 lines of stderr shown)

Concludes with: "Dry run complete — pass --execute to publish."

Execute mode (--execute)

Calls crate_seq_core::publish_workspace_ordered() which publishes crates in topological dependency order with exponential backoff. After each tier, index propagation is awaited before the next tier begins.

Shows an indicatif progress bar during publishing, then reports each version as:

• ✓ version (green) — successfully published
• → version (dim) — already on crates.io
• – version (dim) — skipped
• ✗ version (red) — failed with error message

Snapshot mode

When the ledger's settings.mode is "snapshot", the CLI resolves the snapshot store path (.crate-seq-snapshots/ adjacent to the ledger) and passes it to the pipeline.

Token resolution order

1. --token CLI flag (highest priority)
2. auth.token_cmd — runs the shell command, uses stdout
3. auth.token_env — reads the named environment variable
4. Falls back to cargo login credentials

---

tag

Creates a git tag and a corresponding ledger entry for a new version.

crate-seq tag <VERSION> [--tag-name <TAG>] [--path <DIR>]

Behaviour:

• Parses the version string as strict SemVer
• Creates the git tag and appends a pending entry to the ledger
• Prints: "created tag {tag_name} and ledger entry for {version}"

Errors: InvalidVersion if version string doesn't parse. LedgerNotFound if no .crate-seq.toml exists at the path. Git errors if tag creation fails.

---

skip

Marks a version as skipped so it will not be published.

crate-seq skip <VERSION> [--path <DIR>]

Behaviour:

• Parses the version string as strict SemVer
• Loads the ledger, marks the version as skipped, and saves
• Prints: "skipped {version}"

Errors: InvalidVersion if version string doesn't parse. InvalidTransition if the version is already published (cannot skip a published version).

---

status

Shows a full table of all ledger entries for every crate in the workspace.

crate-seq status [--crate <NAME>] [--path <DIR>]

Output format:

crate-name
  version      source     ref                  status
  ────────────────────────────────────────────────────────
  0.1.0        git-tag    crate-v0.1.0         published
  0.2.0        git-tag    crate-v0.2.0         pending
  ────────────────────────────────────────────────────────
  2 total   1 published   1 pending

Color coding:

• Published — green version and status
• Pending — yellow version and status
• Skipped — dim text
• Yanked — red version and status

Summary line shows totals for published and pending counts.

---

snapshot

Captures the current crate directory as a versioned snapshot. Used when the ledger operates in "snapshot" mode instead of "git-tag" mode.

crate-seq snapshot <VERSION> [--dir <DIR>] [--path <DIR>]

Behaviour:

• Parses the version string as strict SemVer
• Captures the directory as a versioned snapshot and updates the ledger
• Prints: "snapshot created: {sha256} (version {version})"

---

Error handling

All errors from crate_seq_core::Error are caught at the top level by display_error() and formatted as structured, actionable messages with recovery hints before exiting with code 1.

Exit codes

---

Configuration — .crate-seq.toml

Every crate tracked by crate-seq has a .crate-seq.toml ledger file at its root. This file is both configuration and state.

File structure

[crate]
name = "my-crate"              # Crate name as in Cargo.toml (required)
registry = "crates-io"         # Registry alias (optional, defaults to crates.io)

[settings]
mode = "git-tag"               # "git-tag" or "snapshot" (optional)
tag-pattern = "my-crate-v*"    # Glob for matching git tags (optional)
dry-run-default = false        # Default dry-run behaviour (optional)
backoff-base-ms = 1000         # Base delay for exponential backoff (optional)

[auth]
token-env = "CARGO_REGISTRY_TOKEN"  # Env var holding registry token (optional)
token-cmd = "op read ..."           # Shell command to retrieve token (optional)

[[versions]]
version = "0.1.0"
source = "git-tag"             # "git-tag" or "snapshot"
ref = "my-crate-v0.1.0"        # Git tag or snapshot ref
status = "published"           # "published", "pending", "skipped", or "yanked"

Sections

Version lifecycle

---

Typical workflows

First-time setup

cd my-workspace
crate-seq init
crate-seq status

Publishing a new version

crate-seq tag 0.3.0
crate-seq publish              # dry-run first
crate-seq publish --execute    # live publish

Skipping a broken version

crate-seq skip 0.2.1
crate-seq status               # verify it's marked skipped

Snapshot mode (no git tags)

crate-seq snapshot 0.1.0 --dir ./my-crate
crate-seq publish --execute