Generated Service CLIs
Relevant source files
The following files were used as context for generating this wiki page:
Generated Service CLIs are standalone Rust applications produced from a Crucible model. These binaries provide a command-line interface for interacting with a specific HTTP service, leveraging generated Rust clients for typed communication. The system automates the creation of parsing logic, configuration management, shell completion, and output formatting.
Sources: crates/crucible-cli/src/main.rs:405-410, AGENTS.md:73-74
CLI Generation Process
The crucible tool generates a Service CLI by lowering the source model into an intermediate representation (IR) and then emitting a complete Rust package. This process uses a "client view" of the model, which excludes sender-signed operations that are not intended for direct client use.
Sources: crates/crucible-cli/src/main.rs:885-896, AGENTS.md:105-110
Generation Flow
The following diagram illustrates the transformation from a model to a functional binary:
The diagram shows how model semantics like nullability, constraints, and HTTP bindings are preserved through the IR to ensure the generated CLI accurately reflects the service contract.
Sources: AGENTS.md:95-103, crates/crucible-cli/src/main.rs:420-449
Architecture and Runtime Support
Generated CLIs rely on two primary internal components for execution: crucible-cli-runtime and crucible-client-runtime-rust. The crucible-cli-runtime crate manages the user-facing interface, including command-line parsing and result display. The crucible-client-runtime-rust crate handles the underlying HTTP transport, retries, and error decoding.
Sources: AGENTS.md:58-60, AGENTS.md:74-75
Key Runtime Responsibilities
- Parsing: Translates command-line arguments into typed Rust structures.
- Configuration: Manages service endpoints, authentication tokens, and timeouts.
- Completion: Provides shell-native completion for commands and parameters.
- Output: Formats service responses for human readability or machine consumption.
Sources: AGENTS.md:74-75
Command Parameters
When generating a CLI, you must provide specific metadata and path information to the crucible generate cli command.
| Parameter | Type | Description |
|---|---|---|
model | Path | The directory containing the .cru package and crucible.toml. |
out | Path | The destination directory for the generated Rust package. |
bin_name | String | The name of the resulting executable binary. |
package_version | String | The version string for the generated Cargo package. |
endpoint | Option | An optional default URL for the service. |
runtime_path | Path | A local checkout of the Crucible repository containing required runtimes. |
Sources: crates/crucible-cli/src/main.rs:405-419
Required Infrastructure
To emit a Service CLI, the generator validates the runtime_path to ensure it contains a valid Crucible checkout. Specifically, it verifies the existence of Cargo.toml files for both the client and CLI runtimes.
- Navigate to the
runtime_pathprovided. - Check for
crates/crucible-client-runtime-rust/Cargo.toml. - Check for
crates/crucible-cli-runtime/Cargo.toml. - If either is missing, the generation process fails with a diagnostic error.
Sources: crates/crucible-cli/src/main.rs:424-440
Documentation and Documentation Guides
Every generated CLI package includes internal documentation and guides for both human users and coding agents. The README.md provides installation and usage instructions, while AGENTS.md provides terse instructions for coding agents to interact with the package correctly.
Sources: crates/crucible-codegen-common/src/guide.rs:1-15
Generated Service CLIs serve as a critical bridge between the modeled API contract and the developer's terminal. By standardizing the runtime and generation logic, Crucible ensures that CLI tools remain in sync with service updates and provide a consistent user experience across different services.