# AGENTS.md — start-cli

Agent/dev notes for the `start-cli` crate. `CLAUDE.md` is a one-line `@AGENTS.md` import. See
[`ARCHITECTURE.md`](./ARCHITECTURE.md) for this crate's structure.

## 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`):

```sh
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 `projects/start-os/build.mk`), 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.

## Formatting

```bash
make start-cli-format
make start-cli-format-check
cargo clippy -p start-cli
```

## Change ownership

CLI argument/config changes belong in `start-core::context::config` (`ClientConfig`);
CLI entrypoint behavior belongs in `shared-libs/crates/start-core/src/bins/start_cli.rs`.
User-facing CLI documentation lives in `projects/start-sdk/docs/` (packaging)
and `projects/start-os/docs/`.