Gears CLI

Command-line interface for the whole development cycle of Gears projects.

Quickstart

Prerequisites

• Rust toolchain with cargo (https://rust-lang.org/tools/install/)
• If you want to run coverage, install cargo-llvm-cov with cargo +stable install cargo-llvm-cov --locked

Install the CLI

Install it from source:

cargo install cargo-gears

After installation, verify the command surface with:

cargo gears --help

Typical usage flow

1. Create a workspace

Start by generating a new workspace:

cargo gears new /tmp/cf-demo
cd /tmp/cf-demo

The generated workspace is manifest-driven, so you should expect a Gears.toml file alongside the runtime config files under config/.

2. Run the generated server

You can run the workspace straight away with:

cargo gears run --app quickstart --env dev

build and run read generation inputs from Gears.toml, create the generated server project under the workspace generated directory (by default .gears/<name>/), and set GEARS_CONFIG automatically for the generated project.

3. Add a module to the workspace

You can add module templates such as background-worker, api-db-handler, and api-gateway. Prefer passing --name when you want the generated module to use your chosen name instead of the template name. For this example, we'll use background-worker:

cargo gears generate module --template background-worker
cargo gears config mod add background-worker -c /tmp/cf-demo/config/quickstart-dev.yml

Now run it again. You should see the generated background worker outputting its sample messages:

cargo gears run --app quickstart --env dev

You can run the CLI from any directory by specifying the workspace with -p. When omitted, the current directory is used as the workspace root.

What the CLI can do

The current CLI surface is centered on Gears workspace setup, manifest-driven generation, runtime configuration, source inspection, and execution.

Workspace scaffolding

• new initializes a new Gears workspace from a template
• generate module --template <template> adds module templates such as background-worker, api-db-handler, and api-gateway
• generate config --template <template> creates runtime config files such as dev, prod, or db

Configuration management

• ls modules inspects available system and workspace modules
• config mod add and config mod rm manage module entries in the YAML config
• config mod db add|edit|rm manages module-level database settings
• config db add|edit|rm manages shared database server definitions

Configuration commands require the path to the runtime config file with -c, for example:

cargo gears config mod add background-worker -c /tmp/cf-demo/config/app1-dev.yml

Manifest inspection

• manifest validate validates Gears.toml and the selected app/environment inputs
• manifest ls lists the manifest app/environment entries and their resolved config paths

These commands are the safest way to confirm what build, run, lint, and test will use.

Build and run generated servers

• build generates a runnable Cargo project under the manifest workspace.generated-dir directory and builds it
• run generates the same project and runs it; you can use -w for watch mode, --otel for OpenTelemetry, and --fips for the generated manifest's fips feature
• deploy builds a Docker image with the workspace Dockerfile. It requires -c and can optionally use --manifest <Cargo.toml> to build an existing manifest instead of generating one first
• build and run also support --release, --clean, and --dry-run

build and run no longer take -c/--config; they resolve the selected runtime config from Gears.toml using --app <APP> and --env <ENV> or the manifest defaults when they can be inferred.

The generated src/main.rs does not embed the config path. Instead, the generated server reads it from GEARS_CONFIG at runtime. The CLI sets that variable for build and run, but if you execute the generated project or compiled binary yourself, you need to set GEARS_CONFIG manually.

Example manual run of the generated project:

GEARS_CONFIG=/tmp/cf-demo/config/app1-dev.yml cargo run --manifest-path /tmp/cf-demo/.gears/app1-dev/Cargo.toml

Source inspection and help

• src resolves Rust source for crates, modules, and items from the workspace, local cache, or crates.io
• help schema prints manifest, config, or module schema guidance
• help topic prints operational documentation for topics such as manifest, generated-server, fips, and otel
• help src is an alias for src

Linting

cargo gears lint --app <APP> --env <ENV> reads the selected manifest lint policy and orchestrates cargo fmt, cargo clippy, and dylint custom rules for that workspace. It respects your custom settings from Cargo.toml.

Use --all when you want to run every available lint stage explicitly. If the CLI is built without the dylint-rules feature, lint --dylint returns an error.

Testing

cargo gears test --app <APP> --env <ENV> is the manifest-driven test entrypoint. It passes the selected environment config to tests through GEARS_CONFIG, and --coverage uses cargo llvm-cov with the selected runner.

At the moment, the command surface exists, but the implementation is not yet ready for general use.

Tool bootstrap

cargo gears tools can install or upgrade required Rust tooling such as rustup, cargofmt, and clippy.

Command overview

For the full command surface, arguments, examples, and caveats, check SKILL.md.

Local development

To run the CLI from source:

cargo run -p cargo-gears -- gears --help

License

This project is licensed under the Apache License, Version 2.0.

• Full license text: LICENSE
• License URL: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, the software is distributed on an AS IS basis, without warranties or conditions of any kind.