What causes "read CLI command spec" in ccusage/ccusage?

Verify the CLI commands JSON file exists at the path CLI_COMMANDS_JSON points to relative to CARGO_MANIFEST_DIR in the ccusage-cli-parser crate.

ccusage/ccusage · critical

read CLI command spec

Error message

read CLI command spec

What it means

During build script execution (generate_cli_help_rs), the build reads CLI_COMMANDS_JSON via fs::read_to_string and unwraps with expect("read CLI command spec"). If that file cannot be read — it does not exist at the expected path, the path is wrong (CARGO_MANIFEST_DIR-relative), or permissions deny read — the build script panics and cargo reports 'build script panicked at read CLI command spec', failing compilation of the ccusage-cli-parser crate.

Source

Thrown at rust/crates/ccusage-cli-parser/build.rs:23

#[path = "src/help_codegen.rs"]
mod help_codegen;

const CLI_HELP_JSON: &str = "src/cli-help.json";
const CLI_COMMANDS_JSON: &str = "src/cli-commands.json";

fn main() {
    println!("cargo:rerun-if-changed={CLI_HELP_JSON}");
    println!("cargo:rerun-if-changed={CLI_COMMANDS_JSON}");
    generate_cli_help_rs();
}

fn out_dir_path(file_name: &str) -> PathBuf {
    PathBuf::from(env::var_os("OUT_DIR").expect("OUT_DIR is set by cargo")).join(file_name)
}

fn generate_cli_help_rs() {
    let option_source = fs::read_to_string(CLI_HELP_JSON).expect("read CLI help spec");
    let command_source = fs::read_to_string(CLI_COMMANDS_JSON).expect("read CLI command spec");
    let option_sets = serde_json::from_str::<Value>(&option_source).expect("parse CLI help spec");
    let command_spec =
        serde_json::from_str::<Value>(&command_source).expect("parse CLI command spec");
    let output = help_codegen::generate_cli_help_source(&option_sets, &command_spec);
    fs::write(out_dir_path("cli-help.rs"), output).expect("write generated CLI help");
}

View on GitHub (pinned to afebc5d2e0)

Solutions

Verify the CLI commands JSON file exists at the path CLI_COMMANDS_JSON points to relative to CARGO_MANIFEST_DIR in the ccusage-cli-parser crate.
If building a published/packed crate, add the spec JSON to the package include list (package.files or include in Cargo.toml) so cargo publish/ship includes it.
If the spec was renamed, update the CLI_COMMANDS_JSON constant in rust/crates/ccusage-cli-parser/build.rs to the new filename.
Check filename case and permissions on the spec file, especially on Linux CI after a fresh clone.

Example fix

// before (build.rs)
const CLI_COMMANDS_JSON: &str = "cli-commands.json"; // file renamed to cli-commands-spec.json
// after
const CLI_COMMANDS_JSON: &str = "cli-commands-spec.json"; // matches file on disk
// and ensure Cargo.toml includes it:
// [package]
// include = ["cli-commands-spec.json", "cli-help.json", "src/**"]

Defensive patterns

Strategy: validation

Validate before calling

// build.rs: fail with a clear message instead of a bare panic
let command_source = fs::read_to_string(CLI_COMMANDS_JSON).unwrap_or_else(|e| {
    panic!("read CLI command spec at {}: {e}", CLI_COMMANDS_JSON)
});
// pre-flight check in CI:
// test -f cli-commands.json || { echo "missing cli-commands.json"; exit 1; }

Prevention

List spec JSON files in Cargo.toml include/package.files so cargo publish ships them.
Verify a packed crate with cargo package --list before publishing.
Keep spec filenames and the CLI_COMMANDS_JSON constant in sync via a single source of truth.
Add a CI step that builds the crate from `cargo package` output, not just the workspace.

When it happens

Trigger: Running cargo build/check on ccusage-cli-parser when the CLI commands JSON spec file is missing from the package, was renamed or moved, is excluded from the published crate (wrong package.files list), or the build script is executed from a working directory where the relative path no longer resolves.

Common situations: Publishing/packing the crate without including the spec JSON (cargo publish missing file); regenerating the spec under a new filename without updating the build script; a fresh clone on a case-sensitive filesystem where the filename case differs.

Related errors

AI-assisted analysis of ccusage/ccusage@afebc5d2e0 (2026-09-02). Data as JSON: /api/errors/b048297d9446749b. Report an issue: GitHub.