gears
cli reference to help with the development of constructor fabric gears framework. It helps with the development of the framework from its initialization, adding/removing gears, modifying configuration files, build and/or run project, lint the project and managing applications through its manifest. Always load this skill whenever you detect Gears.toml or you locate a reference to gears, cargo-gears, gears-toolkit, gears, plugins or packages that include the prefix cf- in its name.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-29
- Stars
- ★ 5
- Forks
- 7
01 前言 Front Matter
- name
- gears
- description
- cli reference to help with the development of constructor fabric gears framework. It helps with the development of the framework from its initialization, adding/removing gears, modifying configuration files, build and/or run project, lint the project and managing applications through its manifest. Always load this skill whenever you detect Gears.toml or you locate a reference to gears, cargo-gears, gears-toolkit, gears, plugins or packages that include the prefix cf- in its name.
02 资源文件 2
- 其他.dockerignore47 B
- 其他Dockerfile1.3 KB
03 SKILL.md 正文
General Guidelines to follow
- When adding new dependencies use
cargo add, do not edit Cargo.toml manually - When linting, use lint command of the cli to check if there are any lint errors. Do not try to run cargo check, clippy or fmt by your own.
- Always verify that the application runs successfully after modifying the code.
- Unless the user specifically mentions to use a custom module, prefer to use system gears instead of implementing your own ones. Pay attention to the "deps" section of the gears, as the module will be required to be added in order to be used.
- Do not try to create a module from scratch, always use the generate module command to create a new module.
Invocation Forms
The crate exposes a single entrypoint:
- [
cargo gears] Cargo subcommand form via thecargo-gearsbinary
Example:
cargo gears generate workspace /tmp/my-app
Objective
This CLI is a tool for automating gears development, a Rust framework. You can get more information about it in:
- Gears repository main: https://github.com/constructorfabric/cyberware-rust
- Gears libraries(the ones that leverage this CLI tool) are located in https://github.com/constructorfabric/cyberware-rust/tree/main/libs
- More documentation of the project will be located in https://github.com/constructorfabric/cyberware-rust/tree/main/docs
Clone(shallow) the repo to .gears folder (create it if it doesn't exist), and use it as a reference. If so, prefer to use the ssh version instead of https to avoid authentication issues.
Command Tree
cargo gears
├── generate
│ ├── workspace
│ ├── gear
│ └── config
├── new
├── config
│ ├── mod
│ │ ├── add
│ │ ├── db
│ │ │ ├── add
│ │ │ ├── edit
│ │ │ └── rm
│ │ └── rm
│ └── db
│ ├── add
│ ├── edit
│ └── rm
├── src
├── help
│ ├── schema
│ ├── src
│ └── topic
├── lint
├── ls
│ ├── gears
│ ├── templates
│ ├── features
│ ├── deps
│ ├── packages
│ └── targets
├── manifest
│ ├── validate
│ └── ls
├── test
├── tools
│ └── check-version
├── run
├── build
├── clean
└── deploy
Shared Argument Patterns
- [
-p, --path <PATH>] Optional workspace path. When provided toconfig ...,build,run,deploy,lint, andtest, relative config paths, manifest paths, generated project locations, and workspace-scoped lint/test resolution use that directory as the workspace root. When omitted, the current working directory is used as the workspace root. - [
-c, --config <PATH>] Config file path. This is required forconfig ...anddeploycommands because there is no default.buildandrunno longer accept--config; they compose their generation inputs fromGears.tomland forward the manifest-declared runtime config path through theGEARS_CONFIGenvironment variable. - [
--manifest <PATH>] Gears manifest path, defaulting toGears.toml, formanifest,build,run,lint, andtest. Formanifest, you can combine this with-p/--pathto resolve relative manifest paths from a selected workspace. - [
--app <APP> --env <ENV>] Selects a manifest app/environment for manifest-drivenbuild,run,lint, andtest. When omitted, inferred from the manifest: a single app is used automatically; with multiple apps the command fails listing available names. For environments,devis selected by default if it exists; otherwise the command fails listing available names. - [
--name <NAME>] Forbuildandrun, overrides the generated server project and binary name that would otherwise default to the config filename stem. - [
-v, --verbose] Usually enables more logging or richer output. - [name validation] Config-managed names for modules, DB servers, and generated server names only allow letters,
numbers,
-, and_.
What the Tool Manages
From the current implementation, the CLI is mainly for:
- [workspace scaffolding] Initialize a Gears workspace and add module templates
- [config management] Enable modules and patch YAML config sections
- [server generation] Generate a runnable Cargo project under the manifest
workspace.generated-dirdirectory (default.gears/<name>/) - [manifest orchestration] Read
Gears.tomlto separate generation metadata from runtime YAML config - [build/run/clean/deploy] Build, run, clean, or package that generated server as a Docker image
- [source inspection] Resolve Rust source for crates/items through workspace metadata or crates.io
- [module inspection] List workspace-discovered and system-registry modules
- [tool bootstrap] Install or upgrade
rustup,cargofmt, andclippy
Top-Level Commands
generate
Generate workspace, module, and config scaffolding from built-in templates or explicit local/Git template sources.
generate workspace
Synopsis:
cargo gears generate workspace [<path>] [--template <TEMPLATE>] [--list] [--verbose] [--name <NAME>] [--local-path <PATH>] [--git <URL>] [--subfolder <NAME>] [--branch <NAME>] [--override]
Arguments:
- [
<path>] Target directory to initialize; not required with--list - [
-t, --template <TEMPLATE>] Workspace template name, defaults tobasic-init;defaultis accepted as a compatibility alias - [
-l, --list] List built-in workspace templates plus manifesttemplates.workspaceentries when aGears.tomlexists at the selected path - [
-v, --verbose] Verbose output fromcargo-generate - [
-n, --name <NAME>] Override the generated project name; inferred from the final path segment by default - [
--local-path <PATH>] Use a local template directory instead of the default Git template - [
--git <URL>] Override the Git URL for the template - [
--subfolder <NAME>] Override the template subfolder - [
--branch <NAME>] Override the template branch - [
--override] Allow generated files to overwrite existing files
Behavior:
- [creates target directory] If it does not exist
- [fails on file path] Errors if
<path>already exists and is not a directory - [uses directory name as project name] The final path segment becomes the generated project name unless
--nameis provided - [uses template registry] Template names resolve through the built-in registry and then manifest-defined templates
- [forces git init] Template generation runs with Git initialization enabled
- [pins dylint lints] Pins
cargo-gears-lintsto the CLI's release tag in the generated workspace's Dylint metadata, aslint --pin-dylintdoes. If that fails (for example, the template has no workspaceCargo.toml), it only warns
Examples:
cargo gears generate workspace /tmp/cf-demo
cargo gears generate workspace /tmp/cf-demo --git https://github.com/constructorfabric/cf-template-rust --branch main --subfolder Init
cargo gears generate workspace /tmp/cf-demo --local-path ~/dev/cf-template-rust
cargo gears generate workspace --list
generate gear
Generate a gear template inside an existing workspace's gears/ directory and wire Cargo workspace dependencies.
Synopsis:
cargo gears generate gear [--template <TEMPLATE>] [--list] [--name <NAME>] [--path <PATH>] [--verbose] [--local-path <PATH>] [--git <URL>] [--subfolder <NAME>] [--branch <NAME>]
Available built-in templates:
- [
background-worker] Background worker module template - [
api-db-handler] API/database handler module template - [
api-gateway] API gateway module template. Unless the user instruct to implement its own api-gateway, prefer the system module cf-api-gateway
Arguments:
- [
-t, --template <TEMPLATE>] Gear template name; not required with--list - [
-l, --list] List built-in gear templates plus manifesttemplates.gearentries when aGears.tomlexists at the selected path - [
-n, --name <NAME>] Generated gear folder/crate name; defaults to the template name. Prefer passing this when the generated gear should use the user's chosen name. - [
-p, --path <PATH>] Workspace root, defaults to. - [
-v, --verbose] Verbose template generation output - [
--local-path <PATH>] Use a local template directory instead of the default Git template - [
--git <URL>] Override the Git URL for the template - [
--subfolder <NAME>] Override the template subfolder - [
--branch <NAME>] Override the template branch
Behavior:
- [requires
gears/] Fails unless<workspace>/gearsalready exists - [creates
gears/<name>] Uses--namewhen provided, otherwise the template name - [prevents duplicate] Fails if that gear directory already exists
- [updates workspace members] Adds generated modules to
workspace.members - [promotes dependencies] Moves new gear dependency source/version metadata into
workspace.dependencies - [rewrites gear Cargo files] Rewrites gear dependencies to
workspace = true - [inherits workspace lints] Adds
lints.workspace = trueto generated modules if needed - [includes SDK crate when present] If the generated gear contains
sdk/, it is also added as a workspace member
Examples:
cargo gears generate gear --template background-worker -p /tmp/cf-demo
cargo gears generate gear --template background-worker --name jobs -p /tmp/cf-demo
cargo gears generate gear --template rest-api -p /tmp/cf-demo
cargo gears generate gear --list -p /tmp/cf-demo
generate config
Generate a runtime YAML config file from a built-in template.
Synopsis:
cargo gears generate config --template <dev|prod|db> [--app <APP>] [--env <ENV>] [--name <NAME>] [--path <PATH>]
Built-in templates:
- [
dev] Development-friendly runtime config - [
prod] Production-oriented runtime config - [
db] Development config with adatabase.servers.mainsection
Arguments:
- [
-t, --template <TEMPLATE>] Config template name - [
--app <APP>] Application name used for output filename - [
--env <ENV>] Environment name used for output filename - [
--name <NAME>] Custom output filename;.ymlis appended when no YAML extension is provided - [
-p, --path <PATH>] Workspace root, defaults to.
Behavior:
- [writes under
config/] Output path is<workspace>/config/<filename> - [filename resolution]
--namewins; otherwise<app>-<env>.yml,<app>.yml,<env>.yml, or<template>.yml - [prevents overwrites] Fails if the target config file already exists
- [runtime values only] Generated config contains runtime settings, not dependency metadata
Examples:
cargo gears generate config --template dev --app app1 --env dev -p /tmp/cf-demo
cargo gears generate config --template db --name local-db -p /tmp/cf-demo
new
Alias for generate workspace.
Synopsis:
cargo gears new <path> [--template <TEMPLATE>] [--verbose] [--name <NAME>] [--local-path <PATH>] [--git <URL>] [--subfolder <NAME>] [--branch <NAME>] [--override]
config
Manages the YAML application config file used by build and run.
There are two branches:
- [
config mod ...] Module configuration - [
config db ...] Global database server configuration
config mod
Manage the modules section in the app config.
config mod add
Add or update a module entry in the config file's modules section.
Synopsis:
cargo gears config mod add -c <CONFIG> [-p <PATH>] [--package <NAME>] [--module-version <VER>] [--default-features <BOOL>] [-F, --feature <FEATURES>]... [--dep <NAME>]... <module>
Arguments:
- [
<module>] Module name in the config - [
-c, --config <CONFIG>] Required config file path - [
-p, --path <PATH>] Optional workspace directory - [
--package <NAME>] Override metadata package name - [
--module-version <VER>] Override metadata version - [
--default-features <BOOL>] Persist Cargodefault_features - [
-F, --feature <FEATURES>] Feature list; accepts comma-separated values and can be repeated - [
--dep <NAME>] Metadata dependency name; repeat to add more
Behavior:
- [upsert] Creates or updates
modules.<module> - [path activation] If
-p/--pathis provided, Clap changes the current working directory while parsing that value, before-c/--configis resolved - [local-first discovery] Tries to discover module metadata from the workspace
- [remote module support] If the module is not local, you must provide both
--packageand--module-version - [portable metadata] Local filesystem paths are intentionally not persisted into config metadata
- [merge semantics] Existing metadata fields are preserved unless you explicitly override them
- [metadata requirements] Package and version are required in the resulting metadata, whether sourced locally or passed explicitly
Examples:
cargo gears config mod add background-worker -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml
cargo gears config mod add api-gateway -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml -F json,metrics -F tracing --dep authn-resolver --dep tenant-resolver
cargo gears config mod add credstore -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --package cf-credstore --module-version 0.4.2
cargo gears config mod add api-db-handler -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --default-features false
config mod rm
Remove a module from the config file's modules section.
Synopsis:
cargo gears config mod rm -c <CONFIG> [-p <PATH>] <module>
Behavior:
- [path activation] If
-p/--pathis provided, Clap changes the current working directory while parsing that value, before-c/--configis resolved - [strict removal] Fails if the module is not present in config
Example:
cargo gears config mod rm background-worker -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml
config mod db
Manage module-level database config under modules.<module>.database.
Subcommands:
- [
add] Add or patch a module DB config - [
edit] Edit an existing module DB config - [
rm] Remove a module DB config
Shared DB flags:
- [
--engine <postgres|mysql|sqlite>] - [
--dsn <DSN>] - [
--host <HOST>] - [
--port <PORT>] - [
--user <USER>] - [
--password <PASSWORD>] - [
--dbname <NAME>] - [
--params <K=V,...>] - [
--sqlite-file <FILE>] - [
--sqlite-path <PATH>] - [
--pool-max-conns <N>] - [
--pool-min-conns <N>] - [
--pool-acquire-timeout-secs <SECS>] - [
--pool-idle-timeout-secs <SECS>] - [
--pool-max-lifetime-secs <SECS>] - [
--pool-test-before-acquire <BOOL>] - [
--server <NAME>] Reference a named global DB server
Rules:
- [path activation] If
-p/--pathis provided, each subcommand changes the current working directory while Clap is parsing that value, before-c/--configis resolved - [payload required]
addandeditrequire at least one DB-related field - [module must exist]
addrequires the module already exist in config and recommendsconfig mod addfirst - [edit requires existing DB config]
editfails if no module DB config exists yet - [patch semantics]
addandeditpatch only the fields you provide
Examples:
cargo gears config mod db add background-worker -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --server primary
cargo gears config mod db add api-db-handler -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --engine postgres --host localhost --port 5432 --user app --password '${DB_PASSWORD}' --dbname appdb --pool-max-conns 20
cargo gears config mod db edit api-db-handler -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --pool-acquire-timeout-secs 30 --pool-test-before-acquire true
cargo gears config mod db rm api-db-handler -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml
config db
Manage global database server config under database.servers.
Subcommands:
- [
add] Add or upsert a named global DB server - [
edit] Edit an existing global DB server - [
rm] Remove an existing global DB server
Synopsis:
cargo gears config db add -c <CONFIG> [-p <PATH>] <name> <db-flags...>
cargo gears config db edit -c <CONFIG> [-p <PATH>] <name> <db-flags...>
cargo gears config db rm -c <CONFIG> [-p <PATH>] <name>
Behavior:
- [path activation] If
-p/--pathis provided, each subcommand changes the current working directory while Clap is parsing that value, before-c/--configis resolved - [server name] Stored under
database.servers.<name> - [add is upsert]
addcreates or patches an existing server entry - [edit is strict]
editrequires the server to already exist - [payload required]
addandeditrequire at least one DB-related field - [cleanup]
rmremoves the top-leveldatabasesection if it becomes empty andauto_provisionis unset
Examples:
cargo gears config db add primary -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --engine postgres --host localhost --port 5432 --user app --password '${DB_PASSWORD}' --dbname appdb
cargo gears config db edit primary -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --pool-max-conns 30 --pool-idle-timeout-secs 120
cargo gears config db add local-sqlite -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --engine sqlite --sqlite-path /tmp/cf-demo/dev.db
cargo gears config db rm primary -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml
src
Resolve Rust source for a crate/module/item query from local workspace metadata, the local source cache, or crates.io.
Synopsis:
cargo gears src [--path <PATH>] [--registry <REGISTRY>] [--verbose] [--libs] [--version <VERSION>] [--clean] [<query>]
Arguments:
- [
-p, --path <PATH>] Workspace or crate to inspect, defaults to. - [
--registry <REGISTRY>] Registry fallback, defaults tocrates.io - [
-v, --verbose] Print resolution metadata before the source - [
-l, --libs] Printlibrary_name -> package_namemappings for a package query instead of source - [
--version <VERSION>] Resolve a specific crate version after metadata/cache lookup misses - [
--clean] Remove the source cache for the selected registry before resolving - [
[<query>]] Rust path to resolve, starting with the package name; omitted only when--cleanis used by itself
Supported query examples:
- [
cf-gears-toolkit] - [
tokio::sync] - [
cf-gears-toolkit::gts::plugin::BaseGearsPluginV1] - [
cf-gears-toolkit::gts::schemas::get_core_gts_schemas]
Behavior:
- [query requirement] A query is required unless
--cleanis passed by itself - [package-only libs mode]
--libsrequires a package-only query such ascf-gears-toolkit - [local resolution first] Tries workspace metadata before hitting the network
- [cache-first registry fallback] Reuses cached crate sources before downloading from the registry
- [crates.io fallback] Downloads and extracts crate source if local resolution and cache lookup both fail
- [exact version fallback]
--versionpins the registry/cache fallback to that exact crate version - [recursive re-export resolution] Follows re-exports across
crate,self,super, and dependency boundaries until it reaches the final source - [library mapping output]
--libsprints the Rust source-code library name on the left and the Cargo package name on the right, including renamed dependencies likegears_toolkit_macros -> cf-gears-toolkit-macros - [cache location] Registry sources are cached under the OS temp directory in
gears-docs-cache/<registry>/(legacy name) - [cache cleaning]
--cleanremoves the selected registry cache before resolution - [source output] Prints the resolved Rust source to stdout
- [verbose metadata] Also prints query, package, library, version, manifest path, and source path
- [registry support] Only
crates.iois supported today
Examples:
cargo gears src -p /tmp/cf-demo cf-gears-toolkit
cargo gears src cf-gears-toolkit::module
cargo gears src --verbose tokio::sync
cargo gears src --libs cf-gears-toolkit
cargo gears src --version 1.0.217 serde::de::Deserialize
cargo gears src --clean
cargo gears src --clean -p /tmp/cf-demo tokio::sync
help
Schema, topic, and source-code help for developers and LLMs. Groups three subcommands under a single discoverable entry point.
help schema
Print the schema for manifest, config, or module formats.
Synopsis:
cargo gears help schema <manifest|config|module> [--section <SECTION>]
Arguments:
- [
<target>] Schema target:manifest,config, ormodule - [
--section <SECTION>] Drill into a specific section of the schema
Behavior:
- [overview mode] Without
--section, prints a top-level overview of the schema - [section mode] With
--section, prints detailed field documentation for that section - [manifest sections]
workspace,apps,templates - [config sections]
server,database,logging,opentelemetry,modules - [module sections] None (only the overview is available)
Examples:
cargo gears help schema manifest
cargo gears help schema config --section database
cargo gears help schema module
help src
Alias for the top-level src command. Resolves Rust source code from a crate.
Synopsis:
cargo gears help src [--path <PATH>] [--registry <REGISTRY>] [--verbose] [--libs] [--version <VERSION>] [--clean] [<query>]
Behavior identical to src; see the src section above.
help topic
Print operational documentation for a named topic.
Synopsis:
cargo gears help topic <TOPIC>
Available topics:
- [
architecture] Framework architecture, three-tier hierarchy, and principles - [
cli] CLI reference, guidelines, and command overview - [
clienthub] Typed ClientHub, plugins, and GTS - [
database] SecureConn, transactions, migrations, and repository pattern - [
errors] RFC-9457 Problem error handling - [
fips] FIPS mode activation and usage - [
gear-layout] Gear directory structure and SDK pattern - [
gear-refs] How local and remote gears are referenced - [
gears-catalog] Gear categories and dependency rules - [
generated-server] How the ephemeral generated server project works - [
lifecycle] Gear lifecycle, cancellation, and background tasks - [
manifest] Overview ofGears.tomland manifest-driven workflows - [
otel] OpenTelemetry activation and runtime configuration - [
rest-api] OperationBuilder, OpenAPI, SSE, and OData - [
security] AuthN, AuthZ, SecureConn, and AccessScope
Examples:
cargo gears help topic architecture
cargo gears help topic gear-layout
cargo gears help topic generated-server
cargo gears help topic otel
tools
Install or upgrade a small set of Rust tooling dependencies.
Known tool names:
- [
rustup] - [
cargofmt] Installs therustfmtrustup component - [
clippy]
Synopsis:
cargo gears tools (--all | --install <tool,...>) [--upgrade] [--yolo] [--verbose]
Arguments:
- [
-a, --all] Select all known tools - [
--install <tool,...>] Comma-separated tool names - [
-u, --upgrade] Upgrade instead of initial install - [
-y, --yolo] Skip confirmation prompts - [
-v, --verbose] Show subprocess output
Behavior:
- [selection required] You must pass either
--allor--install - [interactive by default] Without
--yolo, the command prompts before installing/upgrading - [rustup bootstrap] If
rustupis missing, the CLI can attempt to install it - [component installs]
cargofmtandclippyare installed throughrustup component add - [upgrade mode] Selected
rustupupgrades viarustup self update; selected components upgrade viarustup update
Examples:
cargo gears tools --all
cargo gears tools --install clippy,cargofmt --yolo
cargo gears tools --install rustup,clippy --upgrade --verbose
tools check-version
Check that an external tool satisfies a semver version requirement by running <tool> --version,
parsing the version from the output, and comparing it against the requirement. Exits 0 (printing
the version) if satisfied, or 1 if not.
Synopsis:
cargo gears tools check-version <TOOL> <REQUIREMENT>
Arguments:
- [
<TOOL>] Tool binary name (e.g.cargo-deny,cargo-nextest) - [
<REQUIREMENT>] Semver requirement (e.g.>=0.20.0,^0.9.130)
Behavior:
- [runs tool] Invokes
<tool> --versionand parses the first semver token from stdout - [exit code] Exits 0 and prints the version if the requirement is satisfied; exits 1 with an error message if not satisfied, if the tool is not installed, or if the version cannot be parsed
Examples:
cargo gears tools check-version cargo-deny '>=0.20.0'
cargo gears tools check-version cargo-nextest '^0.9.130'
run
Generate a server project under the manifest <workspace.generated-dir>/<name> and run it.
Synopsis:
cargo gears run [--app <APP>] [--env <ENV>] [--manifest <Gears.toml>] [-p <PATH>] [--name <NAME>] [--watch|--no-watch] [--otel|--no-otel] [--fips|--no-fips] [--release|--no-release] [--locked] [--clean|--no-clean] [--dry-run]
Arguments:
- [
--manifest <PATH>] Manifest file, defaults toGears.toml - [
--app <APP> --env <ENV>] Manifest app/environment selection (inferred from manifest if omitted) - [
-p, --path <PATH>] Optional workspace directory - [
--name <NAME>] Override the generated server project and binary name; defaults to the config filename stem - [
-w, --watch/--no-watch] Override manifest watch policy on or off - [
--otel/--no-otel] Override manifest OpenTelemetry policy on or off - [
--fips/--no-fips] Override manifest FIPS policy on or off - [
-r, --release/--no-release] Override manifest build profile to release or non-release - [
--locked] RequireCargo.lockis up to date; passed as--lockedtocargo run - [
--clean/--no-clean] Override manifest clean policy on or off - [
--dry-run] Generate the project structure and print the generated files without building or running
Behavior:
- [name resolution] Uses the manifest build policy name when present, otherwise
<app>-<env> - [path activation] If
-p/--pathis provided, Clap changes the current working directory while parsing that value, beforeGears.tomlis resolved and the generated project directory is created - [generates server structure] Writes
<generated-dir>/<name>/Cargo.toml,<generated-dir>/<name>/.cargo/config.toml, and<generated-dir>/<name>/src/main.rs;generated-dircomes from manifestworkspace.generated-dirand defaults to.gears - [runtime config handoff] The generated
src/main.rsreads the config path fromGEARS_CONFIG, andcargo gears runsets that environment variable automatically before invokingcargo run - [dry run]
--dry-runwrites the generated project structure under<generated-dir>/<name>/and prints JSON with the generated project directory plus each generated file path and contents; it does not invoke Cargo build/run - [manifest mode] Reads generation dependencies, runtime config path, and policies from
Gears.toml; runtime YAML stays focused on server configuration - [exclusive boolean overrides] Boolean flag pairs are mutually exclusive. Use either the positive or negative form,
not both; for example,
--otel --no-otelis rejected. When neither side is present, the manifest policy is used. - [runs inside generated project] Executes
cargo runin<generated-dir>/<name>/ - [watch mode] Restarts on runtime config changes and changes in watched local modules; regenerates and reruns when
workspace
Cargo.tomlor the selectedGears.tomlchanges - [watch policy] Manifest
run.watch.includereplaces the default watch set;run.watch.excluderemoves matching paths from either the default set or an explicit include set - [manual generated-project execution] If you invoke the generated project or compiled binary yourself instead of
using
cargo gears run, you must setGEARS_CONFIGmanually
Examples:
cargo gears run -p /tmp/cf-demo --app app1 --env dev
cargo gears run -p /tmp/cf-demo --app app1 --env dev --watch
cargo gears run -p /tmp/cf-demo --app app1 --env dev --otel --fips --release --clean
cargo gears run -p /tmp/cf-demo --app app1 --env dev --name demo-server
cargo gears run -p /tmp/cf-demo --app app1 --env dev --dry-run
cargo gears run -p /tmp/cf-demo --app app1 --env dev --manifest /tmp/cf-demo/Gears.toml
manifest
Inspect and validate Gears manifest files.
Synopsis:
cargo gears manifest [-p <PATH>] [--manifest <Gears.toml>] validate [--format table|json]
cargo gears manifest [-p <PATH>] [--manifest <Gears.toml>] ls [--format table|json]
Behavior:
- [path activation] If
-p/--pathis provided, relative manifest paths are resolved from that workspace directory. - [environment gears] Manifest environments declare generation dependencies under the
gearskey. - [validate] Parses the manifest and resolves every app/environment entry.
- [ls] Lists configured app/environment pairs with their resolved config paths and generated build names.
- [generated structure] Use
build --dry-runorrun --dry-runto write and print the generated project structure.
build
Generate a server project under the manifest <workspace.generated-dir>/<name> and build it.
Synopsis:
cargo gears build [--app <APP>] [--env <ENV>] [--manifest <Gears.toml>] [-p <PATH>] [--name <NAME>] [--otel|--no-otel] [--fips|--no-fips] [--release|--no-release] [--locked] [--clean|--no-clean] [--dry-run]
Arguments:
- [
--manifest <PATH>] Manifest file, defaults toGears.toml - [
--app <APP> --env <ENV>] Manifest app/environment selection (inferred from manifest if omitted) - [
-p, --path <PATH>] Optional workspace directory - [
--name <NAME>] Override the generated server project and binary name; defaults to the config filename stem - [
--otel/--no-otel] Override manifest OpenTelemetry policy on or off - [
--fips/--no-fips] Override manifest FIPS policy on or off - [
-r, --release/--no-release] Override manifest build profile to release or non-release - [
--locked] RequireCargo.lockis up to date; passed as--lockedtocargo build - [
--clean/--no-clean] Override manifest clean policy on or off - [
--dry-run] Generate the project structure and print the generated files without building
Behavior:
- [generates before build] Recreates the generated server project before invoking Cargo
- [name resolution] Uses the manifest build policy name when present, otherwise
<app>-<env> - [path activation] If
-p/--pathis provided, Clap changes the current working directory while parsing that value, beforeGears.tomlis resolved and the generated project directory is created - [exclusive boolean overrides] Boolean flag pairs are mutually exclusive. Use either the positive or negative form,
not both; for example,
--clean --no-cleanis rejected. When neither side is present, the manifest policy is used. - [manifest mode] Reads module dependency metadata, runtime config path, and build/run policy from
Gears.tomlinstead of runtime YAML module metadata - [builds inside generated project] Executes
cargo buildin<generated-dir>/<name>/ - [runtime config source] The generated server no longer embeds the config path; the resulting binary reads it from
GEARS_CONFIGwhen you execute it - [dry run]
--dry-runwrites the generated project structure under<generated-dir>/<name>/and prints JSON with the generated project directory plus each generated file path and contents; it does not invoke Cargo build - [manual generated-project execution] If you later run the generated project or binary outside the CLI, you must
set
GEARS_CONFIGyourself
Examples:
cargo gears build -p /tmp/cf-demo --app app1 --env dev
cargo gears build -p /tmp/cf-demo --app app1 --env dev --release
cargo gears build -p /tmp/cf-demo --app app1 --env dev --otel --fips --clean
cargo gears build -p /tmp/cf-demo --app app1 --env dev --name demo-server
cargo gears build -p /tmp/cf-demo --app app1 --env prod
cargo gears build -p /tmp/cf-demo --app app1 --env prod --dry-run
clean
Superset of cargo clean: removes build artifacts, the generated server project, and its workspace member entry
from the root Cargo.toml.
Synopsis:
cargo gears clean [--app <APP>] [--env <ENV>] [--manifest <Gears.toml>] [-p <PATH>]
Arguments:
- [
--manifest <PATH>] Manifest file, defaults toGears.toml - [
--app <APP> --env <ENV>] Manifest app/environment selection (inferred from manifest if omitted) - [
-p, --path <PATH>] Optional workspace directory
Behavior:
- [runs
cargo cleanfirst] Removes build artifacts from the workspacetarget/directory. If this fails due to a broken workspace (e.g. missing generated member), the error is ignored and cleanup continues -- fixing such broken state is the purpose of this command. Othercargo cleanfailures (permissions, disk errors, etc.) are propagated as errors. - [resolves target without dependencies] Reads
Gears.tomlto determine the generated project directory and name without resolving module dependencies or runningcargo metadata - [deletes generated project] Removes
<generated-dir>/<name>/(e.g..gears/products-dev/) - [removes workspace member] Removes the generated project entry from the
workspace.membersarray in the rootCargo.toml - [cleans up empty generated dir] If the generated directory (e.g.
.gears/) is empty after removal, it is also deleted - [runs
cargo cleanlast] After fixing the workspace, runscargo cleanto remove build artifacts from thetarget/directory. By running last, the workspace is guaranteed to be consistent socargo cleansucceeds even when the generated member was previously missing or broken. - [idempotent] Running
cleanwhen the generated project does not exist is a no-op
Examples:
cargo gears clean
cargo gears clean --app app1 --env dev
cargo gears clean -p /tmp/cf-demo
deploy
Build a Docker image for the generated or provided server manifest.
Synopsis:
cargo gears deploy [--app <APP>] [--env <ENV>] [--manifest <Gears.toml>] [-p <PATH>] [-t <TAG>] [-m <Cargo.toml>] [-c <CONFIG>] [--debug] [--dockerfile <PATH>] [--args <KEY=VALUE>]...
Arguments:
- [
-p, --path <PATH>] Optional workspace directory used to resolve relative manifest paths - [
--manifest <PATH>] Gears manifest file, defaults toGears.toml - [
--app <APP> --env <ENV>] Manifest app/environment selection (inferred from manifest if omitted) - [
-t, --tag <TAG>] Tag for the Docker image; defaults togears:<version> - [
-m, --manifest <Cargo.toml>] Optional Cargo manifest override; when omitted, uses the auto-resolved generated project'sCargo.tomlfrom the selected app/env - [
-c, --config <CONFIG>] Optional config file override; when omitted, uses the config resolved from the Gears.toml manifest - [
--debug] Docker build mode; defaults to release mode. Use this flag to build in debug mode. - [
--dockerfile <PATH>] Dockerfile path to use instead of the default (Dockerfile from workspace root) - [
--args <KEY=VALUE>] DockerfileARGoverride passed asdocker build --build-arg; repeat for multiple overrides
Behavior:
- [manifest selection] Resolves the selected app/environment from
Gears.toml, auto-selecting when there is only one app/env. The generated project'sCargo.tomland config path are derived automatically. - [manifest override] With
-m/--manifest, uses the provided Cargo.toml instead of the auto-resolved one; itspackage.nameis used as the artifact name - [config override] With
-c/--config, uses the provided config path instead of the manifest-resolved one - [Dockerfile bootstrap] If
Dockerfileis missing from the selected workspace root, writes the shared CLI Dockerfile there before running Docker - [build context requirement] The config file and selected manifest must be inside the workspace root because Docker can only copy files from the build context
- [Docker args] The CLI provides
BUILDER_MANIFEST,BUILD_MODE,ARTIFACT_NAME,LOCAL_CONFIG_PATH, andCONFIG_EXT; repeated--argsvalues are appended afterward so they can override Dockerfile arguments
Examples:
# Deploy using Gears.toml auto-selection (single app/env)
cargo gears deploy -p /tmp/cf-demo
# Deploy a specific app/env
cargo gears deploy --app myapp --env dev -t my-app:latest
# Deploy in debug mode
cargo gears deploy --app myapp --env dev --debug
# Deploy with an explicit Cargo manifest override
cargo gears deploy --app myapp --env dev -m .gears/custom-server/Cargo.toml
# Deploy with extra Docker build args
cargo gears deploy --app myapp --env dev --args BUILDER_FLAGS="--features metrics"
lint
Run workspace linting helpers from the selected workspace directory.
Synopsis:
cargo gears lint [--app <APP>] [--env <ENV>] [--manifest <Gears.toml>] [-p <PATH>] [--all] [--fmt] [--clippy] [--strict] [--dylint] [-P <SPEC>]... [--gear <NAME>]... [--include-dependents] [-F <FEATURES>]... [--all-features | --no-default-features] [--locked] [--list] [--pin-dylint]
Arguments:
- [
-p, --path <PATH>] Optional workspace directory used to resolve relative manifest paths - [
--manifest <PATH>] Manifest file, defaults toGears.toml - [
--app <APP> --env <ENV>] Manifest app/environment selection (inferred from manifest if omitted) - [
--all] Runs all available lint suites instead of the selected manifest lint policy - [
--fmt] Runscargo fmt --checkfor the selected package scope; with no-P/--packageor--gear, it uses--all. If passed by itself, it runs only formatting checks. - [
--clippy] Runs workspace Clippy checks; if passed by itself, it runs only Clippy - [
--strict] Turns Clippy warnings into errors; valid only when Clippy is selected explicitly or through--all - [
--dylint] Runscargo dylint --allagainst the workspace rooted at the current or selected directory, which loads every library declared inworkspace.metadata.dylint.libraries. Fails unlesscargo-gears-lintsis declared there and pinned to the CLI's own release tag (see--pin-dylint) - [
-P, --package <SPEC>] Restricts formatting, Clippy, and Dylint to the given workspace package(s); repeatable. Supports Cargo package ID specifications and package-name globs such ascf-gears-*. When omitted together with--gear, the whole workspace is linted. - [
--gear <NAME>] Restricts formatting, Clippy, and Dylint to the local workspace package(s) belonging to a discovered gear; repeatable. Includes the conventional nested gear SDK package. Usecargo gears ls gears --localto list valid names. Can be combined with-P/--package. - [
--include-dependents] Expands the-P/--packageand--gearselection to also include every workspace crate that (transitively) depends on the selected package(s) — the reverse-dependency closure. Requires at least one package or gear selection; otherwise the command fails. - [
-F, --features <FEATURES>] Enables Cargo features for Clippy and Dylint. Accepts comma-separated values and is repeatable. Default features remain enabled unless--no-default-featuresis also passed. - [
--all-features] Enables every Cargo feature. Conflicts with--featuresand--no-default-features. - [
--no-default-features] Disables Cargo default features. May be combined with--features. - [
--locked] RequiresCargo.lockto be up to date; passed to Clippy and Dylint'scargo check. - [
--list] Lists available lint rules instead of running them. When combined with--dylint, lists only the dylint rules. Does not require a manifest or workspace path. - [
--pin-dylint] Writes or updates thecargo-gears-lintsentry inworkspace.metadata.dylint.librariesso it is pinned to the CLI's own release tag, then exits without running lints. Editsdylint.tomlwhen it declares at least one library, otherwise the workspaceCargo.toml; an emptylibraries = []does not count. Fails without editing when both files declare libraries, which Dylint rejects. Other libraries and keys are kept. Conflicts with--all,--fmt,--clippy,--strict,--dylint, and--list.
Behavior:
- [path activation] If
-p/--pathis provided, relative manifest paths are resolved from that workspace directory - [manifest mode] Reads lint policy from the selected
Gears.tomlapp/environment and runs from the resolved manifest workspace root - [default lint selection] With no explicit lint-selection flags,
lintruns the selected manifest lint policy - [explicit selection disables default all] Passing
--fmt,--clippy, and/or--dylintopts into just those requested lint suites unless--allis also provided - [package-scoped formatting]
--fmtrunscargo fmt --check --allwhen no package or gear is selected. With an explicit package/gear scope, it passes each effective package as--package <SPEC>.--include-dependentsexpands this scope before formatting, matching Clippy and Dylint. - [workspace Clippy] Clippy runs as
cargo clippy --workspace --all-targets, or ascargo clippy --package <SPEC> ... --all-targetswhen one or more-P/--packageflags are supplied. Cargo feature flags are appended when selected. Without feature flags, each package's default features are used. Manifestfeature-set-testremains reserved for future feature-matrix linting and is not currently applied. - [strict scope]
--strictis rejected unless Clippy is active through--clippyor--all - [workspace-scoped dylint]
cargo dylintruns from the resolved workspace root with--manifest-path <root>/Cargo.toml, so-p/--pathis the way to lint another workspace without manually changing directories, and a workspace whose metadata cannot be loaded fails the run instead of linting nothing. It runs with--workspace, or with--package <SPEC>for each effective package when a package/gear scope is selected; features, skips, and--lockedare forwarded to itscargo check. - [pinned dylint lints] Before running Dylint, the CLI checks the workspace's Dylint libraries (in
dylint.tomlwhen it declares at least one, otherwise in the workspaceCargo.toml; declaring libraries in both is an error) for exactly onecargo-gears-lintsentry. A git entry must point athttps://github.com/constructorfabric/cargo-gearswithtag = "cargo-gears-v<CLI version>",pattern = "crates/cargo-gears-lints", and nobranchorrev. Apathentry to a localcargo-gears-lintscheckout is accepted with a warning, for developing the lints. A missing, duplicated, or differently pinned entry fails the run and points at--pin-dylint. - [external dylint lints] Any other library in
workspace.metadata.dylint.librariesruns together withcargo-gears-lints, so third-party or in-house Dylint lints need only a standard Dylint entry - [package-scoped linting] Passing one or more
-P/--package <SPEC>flags restricts formatting, Clippy, and Dylint to those packages instead of the whole workspace; the flag is repeatable and supports Cargo package ID specifications plus package-name globs. A bare*intentionally selects every workspace package while remaining an explicit scope. - [gear-scoped linting] Each
--gear <NAME>is resolved through local workspace gear discovery to its annotated package and conventional nested SDK workspace package, when present. Gear-derived packages are merged and de-duplicated with explicit-P/--packageselections. System registry gears that are not local workspace members cannot be selected. - [dependent expansion] With
--include-dependents, the selected packages are expanded to their reverse-dependency closure (the seed packages plus every workspace crate that depends on them) before formatting, Clippy, and Dylint run, so a change to a crate can be linted together with everything it may break. Unknown package names are rejected. - [feature-scoped linting]
--features,--all-features, and--no-default-featuresuse Cargo's standard feature semantics and apply to both Clippy and Dylint. Package-qualified features such ascrate-name/feature-namecan be used when linting multiple workspace packages. - [manifest dylint skips] Manifest
lint.dylint.skipentries are passed to Dylint as allowed rustc lints, so listed rules are ignored for that lint run. They apply to external libraries' lints as well. They are passed both asbuild.rustflagsand appended toDYLINT_RUSTFLAGS, so they still hold whenRUSTFLAGSis set, even to-D warnings. - [tool bootstrap] Before running Dylint, the CLI installs
cargo-dylintanddylint-linkwithcargo install --lockedif either is missing. Dylint itself fetches and builds the declared libraries on the first run, with each library's pinned toolchain, so it needs access to GitHub. - [list mode]
--listprints available lints grouped by category and exits without running any checks.--list --dylintprints only thecargo-gears-lintsrules.--listalone prints all lint suites plus those rules. Lints from other Dylint libraries are not listed.
Examples:
cargo gears lint --app app1 --env dev
cargo gears lint --app app1 --env dev --clippy --strict
cargo gears lint --app app1 --env dev --fmt
cargo gears lint --app app1 --env dev --fmt --gear file-parser
cargo gears lint --app app1 --env dev --dylint
cargo gears lint -p /tmp/cf-demo --app app1 --env dev --dylint
cargo gears lint --app app1 --env dev --clippy --package cf-gears-file-parser
cargo gears lint --app app1 --env dev --dylint -P cf-gears-file-parser -P cf-gears-file-parser-sdk
cargo gears lint --app app1 --env dev --dylint --gear file-parser
cargo gears lint --app app1 --env dev --clippy --gear file-parser --include-dependents
cargo gears lint --app app1 --env dev --clippy -P shared-utils --gear file-parser
cargo gears lint --app app1 --env dev --clippy -P cf-gears-file-parser --include-dependents
cargo gears lint --app app1 --env dev --clippy -P cf-gears-file-parser --features json,otel
cargo gears lint --app app1 --env dev --dylint -P cf-gears-file-parser --no-default-features -F sqlite
cargo gears lint --app app1 --env dev --clippy -P cf-gears-file-parser --all-features
cargo gears lint --list --dylint
cargo gears lint --app app1 --env dev --pin-dylint
cargo gears lint --list
Workspace Cargo.toml pin written by --pin-dylint, next to an external library:
[workspace.metadata.dylint]
libraries = [
{ git = "https://github.com/constructorfabric/cargo-gears", tag = "cargo-gears-v<CLI version>", pattern = "crates/cargo-gears-lints" },
{ git = "https://github.com/example/my-lints", tag = "v1.0.0" },
]
Manifest Dylint skip example:
[apps.app1.dev.lint]
dylint = { enabled = true, skip = ["de0301_no_infra_in_domain"] }
ls
Inspect workspace gears, system gears, templates, features, dependencies, and packages.
ls gears
List all gears — both system-registry and workspace-discovered — in a single unified view.
Synopsis:
cargo gears ls gears [-p <PATH>] [--system] [--local] [--verbose] [--registry crates.io] [--format table|json|list|cargo-flags] [--filter <REGEX>] [--dirs <DIR,...>] [--include-rdeps]
Arguments:
- [
-p, --path <PATH>] Optional workspace directory used for local gear discovery - [
--system] Only print built-in system registry gears - [
--local] Only print workspace-discovered gears - [
-v, --verbose] Show full metadata for both system and local gears (fetches registry metadata for system gears) - [
--registry <REGISTRY>] Registry to query for system-crate metadata; defaults tocrates.io - [
-f, --format <FORMAT>] Output format; defaults tojson. Supported values:table,json,list,cargo-flags - [
--filter <REGEX>] Filter gear names by regex pattern. Applied before--include-rdeps - [
--dirs <DIR,...>] Comma-separated directory paths (relative to workspace root) to restrict results to gears whose crate directory is under one of the given directories. Applied before--include-rdeps - [
--include-rdeps] After filtering/scoping, expand the result set with every workspace crate that transitively depends on the matched gears (reverse-dependency closure)
Behavior:
- [combined output] Prints system gears first, then workspace gears, separated by a blank line
- [filtered output]
--systemprints only system gears;--localprints only workspace gears; passing both is equivalent to the default combined output - [json output]
--format jsonprints amodulesarray with each gear'ssource(systemorlocal), static metadata, and verbose metadata when--verboseis enabled - [system usage marker] System gears include
used: yes/noin table output andused: true/falsein JSON output, based on whetherGears.tomlreferences the system gear as a remote module or the workspace has a discovered gear with the same name - [config-independent] Does not require a
-c/--configfile - [workspace scanning] Local output runs
cargo metadata --no-depsand discovers crates with a gears annotation (#[toolkit::gear(...)]) in anysrc/**/*.rsfile - [system registry] System output uses the compiled-in registry, and
--verbosefetches crate metadata from the selected registry - [cargo-flags format]
--format cargo-flagsprints-p <package>flags suitable for passing to Cargo commands - [filter → scope → rdeps pipeline] Filters and scope directories are applied first to narrow the initial gear
set;
--include-rdepsthen expands that set with reverse dependents
Examples:
cargo gears ls gears
cargo gears ls gears -p /tmp/cf-demo --verbose
cargo gears ls gears --local
cargo gears ls gears --system --verbose
cargo gears ls gears --local --filter 'api-.*' --include-rdeps
cargo gears ls gears --local --dirs gears/api -f cargo-flags
ls templates
List all available generation templates.
Synopsis:
cargo gears ls templates [-p <PATH>]
Arguments:
- [
-p, --path <PATH>] Optional workspace directory used to findGears.toml; defaults to.
Behavior:
- [built-in templates] Always prints built-in workspace and gear templates with their names and descriptions
- [manifest templates] Also prints manifest
templates.workspaceandtemplates.gearentries whenGears.tomlexists at the selected path - [config-independent] Does not require a
-c/--configfile
Examples:
cargo gears ls templates
cargo gears ls templates -p /tmp/cf-demo
ls features
List all feature names defined in a Cargo.toml's [features] section.
Synopsis:
cargo gears ls features --manifest <PATH> [-f <FORMAT>]
Arguments:
- [
--manifest <PATH>] Path to the Cargo.toml to inspect - [
-f, --format <FORMAT>] Output format; defaults tolist. Supported values:list,table,json,cargo-flags
Behavior:
- [sorted output] Features are listed in lexicographic order
- [cargo-flags format]
--format cargo-flagsprints features as a comma-separated list suitable for--features <LIST>
Examples:
cargo gears ls features --manifest gears/api-gateway/Cargo.toml
cargo gears ls features --manifest Cargo.toml -f json
ls deps
List dependency names from a Cargo.toml's [dependencies] section.
Synopsis:
cargo gears ls deps --manifest <PATH> [--non-optional] [-f <FORMAT>]
Arguments:
- [
--manifest <PATH>] Path to the Cargo.toml to inspect - [
--non-optional] Only list non-optional (always-linked) dependencies - [
-f, --format <FORMAT>] Output format; defaults tolist. Supported values:list,table,json,cargo-flags
Behavior:
- [sorted output] Dependencies are listed in lexicographic order
- [package field] Uses the
packagefield from the dependency table when present, otherwise uses the key name - [cargo-flags format]
--format cargo-flagsprints-p <package>flags
Examples:
cargo gears ls deps --manifest gears/api-gateway/Cargo.toml
cargo gears ls deps --manifest Cargo.toml --non-optional -f json
ls packages
List all Cargo packages (crates) in the workspace or under specific directories, with optional filtering and reverse-dependency expansion.
Synopsis:
cargo gears ls packages [-p <PATH>] [--dirs <DIR,...>] [--filter <REGEX>] [--include-rdeps] [-f <FORMAT>]
Arguments:
- [
-p, --path <PATH>] Optional workspace directory - [
--dirs <DIR,...>] Comma-separated directory paths to restrict discovery to crates under those directories (relative to workspace root) - [
--filter <REGEX>] Filter package names by regex pattern. Applied before--include-rdeps - [
--include-rdeps] After filtering/scoping, expand the result set with every workspace crate that transitively depends on the matched packages (reverse-dependency closure) - [
-f, --format <FORMAT>] Output format; defaults tolist. Supported values:list,table,json,cargo-flags
Behavior:
- [all packages by default] Without
--dirs, lists all workspace packages - [dirs discovery] With
--dirs, only packages whose manifest path is inside one of the given directories are included - [scope → filter → rdeps pipeline] Scoping is applied first, then filters, then
--include-rdepsexpands the filtered set - [cargo-flags format]
--format cargo-flagsprints-p <package>flags
Examples:
cargo gears ls packages -p /tmp/cf-demo
cargo gears ls packages -p /tmp/cf-demo --dirs gears/api
cargo gears ls packages --filter 'cf-gears-.*' --include-rdeps
cargo gears ls packages --filter 'api' --include-rdeps -f cargo-flags
test
Orchestrates manifest-driven Rust tests with either cargo test or the in-process nextest runner.
Synopsis:
cargo gears test [-p <PATH>] [--manifest <PATH>] [--app <APP>] [--env <ENV>] [--runner <cargo|nextest>] [--module <NAME>] [--include-dependents] [--coverage] [--locked]
Arguments:
- [
--runner <cargo|nextest>] Overrides the manifesttest.runner; defaults tonextestthat it's integrated in the tool - [
--module <NAME>] Limits tests to a module/package. When manifesttest.feature-setcontains that module, its feature matrix is used. - [
--include-dependents] Also tests every workspace crate that (transitively) depends on--module— the reverse-dependency closure. Requires--module; has no effect on its own. - [
--coverage] Runs coverage withcargo llvm-covusing the selected or manifest test runner - [
--locked] RequireCargo.lockis up to date; passed as--lockedtocargo test, nextest build, andcargo llvm-cov
Behavior:
- [manifest selection] Resolves the selected app/environment and passes its config path to tests via
GEARS_CONFIG - [cargo runner] Runs
cargo testwith--workspaceby default, or-p <package>for module-specific runs - [nextest runner] Builds test binaries with Cargo JSON messages, then executes them through the embedded nextest runner from
cargo-nextest - [coverage runner] Cleans llvm-cov artifacts once, executes every selected module/feature-set run, then generates one aggregate report across all collected profiles
- [cargo coverage] With
cargo, runs each selected module/feature-set throughcargo llvm-cov --no-report --no-clean, then reports once withcargo llvm-cov report - [nextest coverage] With
nextest, usescargo llvm-cov show-env, runs the embedded nextest runner under the coverage environment for every selected module/feature-set, then reports once withcargo llvm-cov report - [feature-set policy] Expands manifest
test.feature-setmodule entries bymode:all-featuresuses--all-features,no-default-featuresuses--no-default-features,default-featuresuses Cargo defaults, andfeaturesuses--no-default-features --features <LIST> - [dependent expansion] With
--module <NAME> --include-dependents, the resolved package is expanded to its reverse-dependency closure and each additional dependent crate is added as a default-feature test run (de-duplicated against runs already produced by the feature-set policy)
Practical End-to-End Flows
Create a workspace and run it
cargo gears {new|generate workspace} /tmp/cf-demo
cargo gears generate module --template background-worker -p /tmp/cf-demo
cargo gears generate config --template dev --app app1 --env dev -p /tmp/cf-demo
cargo gears config mod add background-worker -p /tmp/cf-demo -c /tmp/cf-demo/config/app1-dev.yml
cargo gears run -p /tmp/cf-demo --app app1 --env dev
Add a module and wire a shared DB server
cargo gears generate module --template api-db-handler -p /tmp/cf-demo
cargo gears config db add primary -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --engine postgres --host localhost --port 5432 --user app --password '${DB_PASSWORD}' --dbname appdb
cargo gears config mod add api-db-handler -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml
cargo gears config mod db add api-db-handler -p /tmp/cf-demo -c /tmp/cf-demo/config/quickstart.yml --server primary
cargo gears run -p /tmp/cf-demo --app app1 --env dev --watch
Inspect source for a dependency
cargo gears src --verbose tokio::sync
Important Caveats
- [
-c/--configis mandatory] Forconfig ...anddeploy;buildandrunuseGears.tomlinstead - [generated servers expect
GEARS_CONFIG]cargo gears runsets it for you, but manual execution of generated project directory or its compiled binary must provide it explicitly - [
lint --dylintneeds the lints pinned] Runcargo gears lint --pin-dylintafter creating a workspace by other means thangenerate workspace, and after every CLI upgrade - [
lint --strictdepends on Clippy] Use it together with--clippyor--all - [
testis not ready] It is part of the CLI surface but currently panics at runtime - [
toolscan mutate your system] It may installrustupor rustup components - [
src --registry] Onlycrates.iois supported - [
src] Accepts a single query, and that query is only optional when--cleanis used by itself - [
config mod add] Remote modules require both--packageand--module-version - [
config mod db add] The module must already exist in config
Quick Reference
cargo gears {new|generate workspace} <path> [--template <template>] [--name <name>]
cargo gears generate module --template <background-worker|api-db-handler|api-gateway> [--name <name>] [-p <workspace>]
cargo gears generate config --template <dev|prod|db> [--app <app>] [--env <env>] [--name <name>] [-p <workspace>]
cargo gears config mod add <module> [-p <workspace>] -c <config>
cargo gears config mod rm <module> [-p <workspace>] -c <config>
cargo gears config mod db add <module> [-p <workspace>] -c <config> ...
cargo gears config mod db edit <module> [-p <workspace>] -c <config> ...
cargo gears config mod db rm <module> [-p <workspace>] -c <config>
cargo gears config db add <name> [-p <workspace>] -c <config> ...
cargo gears config db edit <name> [-p <workspace>] -c <config> ...
cargo gears config db rm <name> [-p <workspace>] -c <config>
cargo gears ls gears [-p <workspace>] [--system] [--local] [--verbose] [--registry crates.io] [-f table|json|list|cargo-flags] [--filter <regex>] [--dirs <dirs>] [--include-rdeps]
cargo gears ls templates [-p <workspace>]
cargo gears ls features --manifest <Cargo.toml> [-f list|json|cargo-flags]
cargo gears ls deps --manifest <Cargo.toml> [--non-optional] [--dev] [--build] [-f list|json|cargo-flags]
cargo gears ls packages [-p <workspace>] [--dirs <dirs>] [--filter <regex>] [--include-rdeps] [-f list|json|cargo-flags]
cargo gears ls targets --manifest <Cargo.toml> [-f list|json|cargo-flags]
cargo gears src [-p <path>] [--version <version>] [--clean] [<query>]
cargo gears lint [-p <workspace>] [--app <app>] [--env <env>] [--manifest <Gears.toml>] [--all] [--fmt] [--clippy] [--strict] [--dylint] [-P <spec>]... [--gear <name>]... [--include-dependents] [-F <features>]... [--all-features | --no-default-features] [--locked] [--list] [--pin-dylint]
cargo gears tools --all
cargo gears tools check-version <tool> '<requirement>'
cargo gears run [-p <workspace>] [--app <app>] [--env <env>] [--manifest <Gears.toml>] [--name <name>] [--watch] [--locked]
cargo gears build [-p <workspace>] [--app <app>] [--env <env>] [--manifest <Gears.toml>] [--name <name>] [--locked]
cargo gears deploy [--app <app>] [--env <env>] [-p <workspace>] [-t <tag>] [-m <Cargo.toml>] [-c <config>] [--debug] [--args <KEY=VALUE>]...