AGENTS.md — start-cli

Agent/dev notes for the start-cli crate. CLAUDE.md is a one-line @AGENTS.md import. See ARCHITECTURE.md and CONTRIBUTING.md for this crate, and the root AGENTS.md and CONTRIBUTING.md for repo-wide rules.

Read up the tree first. These docs are hierarchical: before working here, read the AGENTS.md in each enclosing directory up to the repo root (and their ARCHITECTURE.md / CONTRIBUTING.md where relevant). This file covers only what is specific to this scope and does not repeat rules already stated higher up.

What this is

A thin bin crate (start-cli) over start-core (cargo package start-core, lib start_core, at shared-libs/crates/start-core). All CLI logic lives in start-core; this crate is just the entrypoint (src/main.rs) and feature/bin wiring (Cargo.toml).

Layout

• src/main.rs — the entrypoint (STARTOS_USE_PODMAN/PREFER_DOCKER wiring, builds the MultiExecutable, enables the start-cli sub-bin, and execute()s).
• Cargo.toml — declares the start-cli bin, the start-core dependency, and the feature flags.
• man/ — committed man pages generated by start-core's export_manpage_start_cli test.
• build/build-cli.sh — release musl/darwin build via the rust-zig-builder container (what make start-cli runs; --install copies the binary to ~/.cargo/bin).

Build & test (run from the repo root)

From the monorepo root (one Cargo workspace, one Cargo.lock):

make start-cli                                             # build the start-cli bin
cargo build -p start-cli --bin start-cli             # dev shortcut (debug)
cargo build -p start-cli --bin start-cli --release   # dev shortcut (release)
cargo check -p start-cli                              # fast type-check (linux-only locally)
target/debug/start-cli --help                        # smoke test

There are no tests in this crate itself. CLI behavior is tested in start-core; the man-page generator is cargo test -p start-core export_manpage_start_cli.

Gotchas

• Don't add command logic here. New/changed subcommands go in start-core — main_api() in shared-libs/crates/start-core/src/lib.rs plus the relevant src/<area>/ module. This crate changes only for entrypoint, feature, or bin-wiring edits.
• start-core is depended on by package name in Cargo.toml (start-core = { path = "../../shared-libs/crates/start-core" }). src/main.rs imports it as start_core::... (the crate's lib name).
• Feature flags forward to start-core (beta, console, dev, test, unstable); none on by default. Keep them in sync with start-core's features when adding new ones.
• STARTOS_USE_PODMAN controls the local container backend for s9pk packaging. Unset or falsey → PREFER_DOCKER is set (Docker). Truthy (1/true/y/yes) → Podman.
• In a StartOS image start-cli is a symlink to startbox (see OS Makefile), the same MultiExecutable multiplexer. The standalone bin here enables only the start-cli sub-bin.

Verifying a command

Build the bin, then run it against a StartOS test VM. Remote commands need -H https://<ip> and an auth login; local commands (s9pk, init-key, pubkey, util) need no server.