--- name: adom-cli-design description: Guidelines for building CLI tools in the Adom ecosystem. Use when creating a new CLI, adding commands to an existing one, or deciding between CLI vs MCP vs HTTP API. Covers Rust CLI conventions, AI-oriented output, skill files, and why we prefer CLIs over MCP servers. Trigger words: build a cli, new cli tool, cli design, cli guidelines, mcp vs cli, should I use mcp, make a tool for the ai. --- # Building CLI Tools for Adom ## Why CLI over MCP We use Rust CLIs as the primary interface between Claude Code and Adom tools. **Do not build MCP servers** for new tools. | | MCP Server | Rust CLI | |---|---|---| | Context cost | High — tool schemas injected into every conversation | Zero — skill file loaded only when triggered | | Discoverability | Always visible, clutters tool list | Skill-triggered, on-demand | | Reliability | Stdio transport can hang, crash, or desync | Process runs and exits cleanly | | Debugging | Opaque — hard to see what happened | Just run the command in terminal | | Distribution | Requires .mcp.json wiring per container | Single binary, `cp` to `/usr/local/bin/` | | AI usability | AI must guess tool params from schema | AI reads skill examples, runs bash | **The pattern:** Rust CLI binary + Claude Code skill file. The AI reads the skill to learn the commands, then runs them via Bash. ## CLI Conventions ### Language: Rust - Use `clap` with derive macros for argument parsing - Use `serde_json` for JSON input/output - Minimize dependencies — prefer raw TCP over `reqwest` for simple HTTP calls - Build with `--release`, `opt-level = "z"`, `lto = true`, `strip = true` for small binaries - Install to `/usr/local/bin/` so it's on PATH everywhere ### Output: AI-Oriented The CLI output is consumed by Claude Code, not humans. Design accordingly: **Every response starts with `OK:` or `ERROR:`** — the AI can instantly determine success/failure. **Success output is descriptive and confirms what happened:** ```text OK: Opened /home/adom/project/README.md in VS Code editor tab. OK: Injected shot-2026-03-28T14-30-22.png (1920x1080, 245 KB) into channel "dart2". OK: Server listening on port 8820, recovered 3 channels from disk. ``` **Error output includes a `Hint:` line with the next action:** ```text ERROR: Cannot connect to shotlog server on port 8820. Hint: Start the server with `shotlog serve &` ERROR: File not found: /home/adom/project/missing.png Hint: Check the path exists. Use `ls /home/adom/project/` to list files. ERROR: Adom Bridge extension not responding on port 8821. Hint: The extension may need a window reload. Run: adom-bridge health ``` **Never output ambiguous or empty responses.** If a command succeeds silently, still print `OK:`. ### Colored output Use ANSI escape codes for colored terminal output. No crate needed — raw escape codes work everywhere. But colors are for **humans at interactive terminals only**: when the CLI's output is piped (`cmd | grep`, `cmd > log`, `nohup cmd > log.txt 2>&1`, bash command substitution, etc.), ANSI escape codes leak into log files and into the AI's stdout capture as ugly garbage like `[36mstarting server[0m`. Every CLI MUST strip ANSI when stdout/stderr is not a TTY. **Required pattern** — `is_terminal()` check gated on each output helper, with a matching `strip_ansi` fallback. Both `println!` / `eprintln!` calls that embed color constants AND internal progress messages need this — not just the `ok` / `err` / `hint` / `warn` helpers: ```rust use std::io::IsTerminal; use std::sync::OnceLock; const GREEN: &str = "\x1b[32m"; const RED: &str = "\x1b[31m"; const YELLOW: &str = "\x1b[33m"; const CYAN: &str = "\x1b[36m"; const BOLD: &str = "\x1b[1m"; const DIM: &str = "\x1b[2m"; const RESET: &str = "\x1b[0m"; static STDOUT_IS_TTY: OnceLock = OnceLock::new(); static STDERR_IS_TTY: OnceLock = OnceLock::new(); pub fn stdout_is_tty() -> bool { *STDOUT_IS_TTY.get_or_init(|| std::io::stdout().is_terminal()) } pub fn stderr_is_tty() -> bool { *STDERR_IS_TTY.get_or_init(|| std::io::stderr().is_terminal()) } pub fn strip_ansi(s: &str) -> String { // Strip CSI sequences like \x1b[36m, \x1b[0m, \x1b[1;32m etc. let mut out = String::with_capacity(s.len()); let mut chars = s.chars().peekable(); while let Some(c) = chars.next() { if c == '\x1b' && chars.peek() == Some(&'[') { chars.next(); for c2 in chars.by_ref() { if c2.is_ascii_alphabetic() { break; } } continue; } out.push(c); } out } fn ok(msg: impl std::fmt::Display) { if stdout_is_tty() { println!("{GREEN}{BOLD}OK:{RESET} {msg}"); } else { println!("OK: {}", strip_ansi(&msg.to_string())); } } fn err(msg: impl std::fmt::Display) { if stderr_is_tty() { eprintln!("{RED}{BOLD}ERROR:{RESET} {msg}"); } else { eprintln!("ERROR: {}", strip_ansi(&msg.to_string())); } } fn hint(msg: impl std::fmt::Display) { if stderr_is_tty() { eprintln!("{DIM}Hint:{RESET} {msg}"); } else { eprintln!("Hint: {}", strip_ansi(&msg.to_string())); } } // And — critically — `note!` for every internal progress message // ("starting server on port X", "running ffmpeg...", "filter graph: // N chars", etc.). These are the ones that tend to get written as // bare `println!("{CYAN}...{RESET}")` and leak raw escape codes into // logs when the CLI is run under nohup or backgrounded to a file. // Route them all through a `note!` macro so the isatty gate is // unmissable: macro_rules! note { ($($arg:tt)*) => {{ let __s = format!($($arg)*); if $crate::stdout_is_tty() { println!("{}", __s); } else { println!("{}", $crate::strip_ansi(&__s)); } }}; } ``` - `OK:` in green bold, paths/values in cyan, search terms in yellow. - `ERROR:` in red bold, hints in dim. - The AI reads `OK:` / `ERROR:` prefixes; colors are for human readability **only**. - **Never leak raw ANSI escape codes to pipes.** If you see `[36m` or `[0m` in a log file, a CLI is broken. The `video-post` crate (adom-inc/video-post on GitHub) implements the full pattern above in `src/main.rs` — `note!` + `enote!` macros + `ok/err/hint/warn` helpers all gated on isatty. Copy from there for any new CLI. ### Bash tab completions Use `clap_complete` to generate bash completions. The `install` command should write them to `~/.local/share/bash-completion/completions/` and append an `eval` line to `.bashrc`: ```rust // In Cargo.toml: clap_complete = "4" // Generate completions: let mut cmd = Cli::command(); let mut buf = Vec::new(); clap_complete::generate(clap_complete::Shell::Bash, &mut cmd, "my-tool", &mut buf); fs::write(format!("{completions_dir}/my-tool"), &buf).ok(); ``` Users get tab completion immediately in new terminals -- `my-tool ` shows all subcommands. ### Subcommand Structure Use subcommands for logical grouping: ```text toolname [options] [args] shotlog serve --port 8820 shotlog inject --channel dart2 --desc "..." file.png shotlog open --channel dart2 adom-bridge open /path/to/file.png adom-bridge reveal /path/to/folder/ adom-bridge claude new adom-bridge extensions search "python" ``` ### Port Registration **Before picking a port**, check `/home/adom/gallia/PORT-REGISTRY.md`. Add your service to the registry before writing code. Port ranges are pre-allocated by category (8820–8829 for Adom tools, 8850–8899 for user/ephemeral, etc.). ### Health Check Every CLI that talks to a server should have a `health` subcommand: ```text toolname health ``` Returns `OK: ...` if the server is reachable, `ERROR: ...` with a hint if not. This lets the AI self-diagnose connection issues. ## Skill File Every CLI **must** have a `SKILL.md` so Claude Code knows how to use it. ### Where it lives - Source: in the tool's own repo (e.g., `/home/adom/project/my-tool/SKILL.md`) - Embedded in the binary via `include_str!` - Deployed to `~/.claude/skills//SKILL.md` by `my-tool install` ### What it contains ```markdown --- name: tool-name description: "One-line description with trigger words..." --- # Tool Name Brief description of what it does. ## Commands ### `toolname verb` What it does. | Flag | Required | Default | Description | |------|----------|---------|-------------| | `--flag` | yes | — | What it controls | **Example:** \`\`\`bash toolname verb --flag value /path/to/thing \`\`\` ``` Include **concrete examples** for every command. The AI copies from examples — if the example is wrong or missing, the AI will guess and get it wrong. ### Register in the capabilities table Add a row to `~/.claude/skills/adom/SKILL.md`: ```text | Tool Name | "trigger words" | Standalone skill: `~/.claude/skills//SKILL.md` | ``` ## Distribution ### Own GitHub repo (recommended) Every shared CLI should live in its own `adom-inc/` repo. This keeps the tool self-contained, gives it its own release cycle, and avoids bloating gallia with build artifacts. Examples: `adom-inc/adom-cli`, `adom-inc/adom-vscode`. ### The `install` command pattern **The binary owns its own install.** One command — `my-tool install` — sets up everything: the skill, shell completions, companion pieces (VSIX, config files, etc.). `gallia/install.mjs` just downloads the binary and runs it. #### DO NOT embed SKILL.md / BUILD-SKILL.md in the binary (hard rule) Skills are prose, and we edit them *a lot* more often than we rebuild the Rust code — adding triggers, clarifying tool-use patterns, patching a broken sentence an AI misinterpreted. If a skill is compiled into the binary via `include_str!`, every single prose fix requires a full binary rebuild, a GitHub release, a wiki asset upload, and a re-install on every user container. That's way too much ceremony for a 10-character typo. Worse: until a user reinstalls the binary, they silently run the stale skill. **The rule:** - SKILL.md and BUILD-SKILL.md ship as **independent assets on the wiki page**. Upload them alongside the binary: ```bash adom-wiki asset upload apps/my-tool --asset-type skill --file SKILL.md adom-wiki asset upload apps/my-tool --asset-type build-skill --file BUILD-SKILL.md ``` - The binary's `install` subcommand **fetches the latest SKILL.md from the wiki** at install time (and falls back to a bundled copy if the wiki is unreachable). The fallback is a safety net, not the primary path. - Bumping a skill becomes: edit `SKILL.md` in the repo → `adom-wiki asset upload …` → done. No binary rebuild, no version bump. The next user to run `my-tool install` (or re-run gallia's Tier A refresh) picks up the new prose. Same rule applies to any other rapidly-changing prose asset (policy docs, prompt templates, wiki `body.md`). Binary-side data that is *strictly coupled* to the binary's own structure (e.g., a `VSIX` whose API matches the current binary's RPC schema, or baked-in default config schemas used by the Rust types) can still be embedded via `include_bytes!` — couple-to-code, not couple-to-prose. #### Implementation — `install` subcommand 1. **Fetch skill from the wiki, fall back to a bundled copy:** ```rust // Bundled SKILL.md is the fallback used only when the wiki is unreachable. // `// SAFETY NET — do not rely on for release propagation.` const FALLBACK_SKILL_MD: &str = include_str!("../../SKILL.md"); fn fetch_skill_md() -> Cow<'static, str> { let url = "https://wiki-ufypy5dpx93o.adom.cloud/static/apps/my-tool/SKILL.md"; match ureq::get(url).timeout(Duration::from_secs(5)).call() { Ok(r) => r.into_string().map(Cow::Owned).unwrap_or(Cow::Borrowed(FALLBACK_SKILL_MD)), Err(_) => { warn("wiki unreachable — installing bundled SKILL.md (may be stale)"); Cow::Borrowed(FALLBACK_SKILL_MD) } } } ``` 2. **Add an `install` subcommand** that handles all setup: ```rust Commands::Install => { // 1. Install companion pieces (VSIX, config, etc.) // 2. Install skill — fetched fresh from the wiki let skill_dir = format!("{home}/.claude/skills/my-tool"); fs::create_dir_all(&skill_dir).ok(); fs::write(format!("{skill_dir}/SKILL.md"), fetch_skill_md().as_ref()).ok(); // 3. Install bash completions let comp_dir = format!("{home}/.local/share/bash-completion/completions"); fs::create_dir_all(&comp_dir).ok(); let mut cmd = Cli::command(); let mut buf = Vec::new(); clap_complete::generate(Shell::Bash, &mut cmd, "my-tool", &mut buf); fs::write(format!("{comp_dir}/my-tool"), &buf).ok(); // 4. Add to .bashrc if not already there let bashrc = fs::read_to_string(format!("{home}/.bashrc")).unwrap_or_default(); if !bashrc.contains("# my-tool completions") { fs::OpenOptions::new().append(true).open(format!("{home}/.bashrc")) .map(|mut f| f.write_all(b"\n# my-tool completions\neval \"$(my-tool completions bash 2>/dev/null)\"\n")).ok(); } } ``` 3. **Attach binary to GitHub Releases** — no Rust toolchain needed on user containers 4. **`gallia/install.mjs` is just two lines:** ```javascript execSync('gh release download --repo adom-inc/my-tool --pattern "my-tool" --output /usr/local/bin/my-tool --clobber'); execSync('sudo chmod +x /usr/local/bin/my-tool && my-tool install'); ``` The binary is the primary artifact for *code*. The wiki is the primary artifact for *prose*. `gallia/install.mjs` never needs to know the internals — it just downloads the binary and runs `install`, which then reaches back to the wiki for the skills. ### build.sh (for local development) Every tool should have a `build.sh` for building locally before cutting a release: 1. Build the binary (`cargo build --release`) 2. Install to `/usr/local/bin/` 3. Run `my-tool install` (installs everything locally) ## Examples of This Pattern | Tool | Port | What it does | |------|------|-------------| | `shotlog` | 8820 | Screenshot log viewer + injector | | `adom-vscode` | 8821 | VS Code control API (open files, reveal, extensions, Claude Code) | | `adom-cli` | — | Adom platform API (containers, repos, users, workspaces) |