Macro CLI: Command-Line Interface Guide for the Macro Platform

The Macro CLI is a clap-based command-line interface that provides subcommands for dev, deploy, test, and run operations, defined in tooling/xtask/crates/xtask_local/src/local/cli.rs and distributed as the macro binary.

The Macro platform includes a dedicated command-line interface (CLI) built on Rust's clap crate. This tool enables developers and operators to manage local development, service deployment, and runtime tasks through a structured subcommand hierarchy. The CLI ships as part of the workspace's xtask tooling and is exposed through the macro executable.

How the Macro CLI Is Structured

The Macro CLI follows a standard Rust command-line pattern using clap's derive macros. The implementation separates command definitions from execution logic across multiple source files.

Core CLI Definition

The primary CLI definition resides in tooling/xtask/crates/xtask_local/src/local/cli.rs. This file uses #[derive(Parser)] and #[derive(Subcommand)] to define the command hierarchy and argument structures.

// From tooling/xtask/crates/xtask_local/src/local/cli.rs
#[derive(Parser)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Commands,
}

#[derive(Subcommand)]
pub enum Commands {
    Dev,
    Deploy { service: String },
    Test,
    Run { task: String },
}

The Parser derive generates the argument parsing logic, while Subcommand creates the nested command structure that users interact with.

Binary Declaration

The macro binary is declared in tooling/xtask/Cargo.toml under a [[bin]] section. This configuration produces the executable that users invoke:

# From tooling/xtask/Cargo.toml

[[bin]]
name = "macro"
path = "src/main.rs"

Available Macro CLI Commands

The Macro CLI exposes four primary subcommands for different operational contexts:

Command	Purpose	Example Usage
dev	Start local development orchestration	macro dev
deploy	Deploy a specific micro-service	macro deploy api-gateway
test	Run test suites for components	macro test
run	Execute custom tasks like migrations	macro run db-migrate

Each subcommand variant in the Commands enum maps to a dedicated Rust module that implements the requested functionality.

Running the Macro CLI

Developers can invoke the Macro CLI through two primary methods:

Via cargo for development:

cargo run -p xtask -- dev
cargo run -p xtask -- deploy <service-name>

As an installed binary:

macro dev
macro deploy <service>
macro test
macro run <task>

The CLI automatically forwards unknown arguments to the underlying subcommand parser, enabling extensibility without modifying the top-level definition.

Key Source Files for the Macro CLI

Understanding the file structure helps when extending or debugging the CLI:

• tooling/xtask/crates/xtask_local/src/local/cli.rs — Defines the clap-based CLI with Parser and Subcommand derives and argument structs.

• tooling/xtask/Cargo.toml — Declares the macro binary via the [[bin]] entry point.

• tooling/xtask/crates/xtask_local/src/local/stack.rs — Contains auxiliary argument structs (Args) consumed by CLI commands.

• tooling/xtask/crates/xtask_local/src/main.rs — Entry point that wires the CLI into the broader xtask orchestration system.

Extending the Macro CLI

The derive-based architecture in cli.rs supports straightforward extension. Adding a new subcommand requires:

1. Adding a variant to the Commands enum with #[derive(Subcommand)]
2. Creating the corresponding argument struct with #[derive(Parser)]
3. Implementing the execution logic in a dedicated module
4. Wiring the handler in the main entry point

The automatic argument forwarding ensures subcommands can accept their own flags and options without central coordination.

Summary

• The Macro CLI is built on the clap crate using derive macros (Parser, Subcommand) in tooling/xtask/crates/xtask_local/src/local/cli.rs.
• Four primary subcommands—dev, deploy, test, run—cover development, deployment, testing, and task execution workflows.
• The binary is produced from the xtask workspace and invoked as macro or via cargo run -p xtask --.
• Auxiliary argument structures live in stack.rs, with orchestration wired through main.rs.

Frequently Asked Questions

How do I install the Macro CLI?

The Macro CLI builds from the xtask workspace in the macro-inc/macro repository. Run cargo build -p xtask to compile, or use cargo run -p xtask -- <command> for development without installation. The binary name is macro as declared in tooling/xtask/Cargo.toml.

Where is the Macro CLI source code located?

The CLI definition using clap derives lives in tooling/xtask/crates/xtask_local/src/local/cli.rs. The binary entry point is tooling/xtask/crates/xtask_local/src/main.rs, and supporting argument types are in tooling/xtask/crates/xtask_local/src/local/stack.rs.

What arguments does the Macro CLI support?

Each subcommand (dev, deploy, test, run) accepts its own specific arguments. The deploy and run commands both take a required string argument (service or task respectively). The CLI forwards additional flags automatically to subcommand parsers for extensibility.

Can I add custom commands to the Macro CLI?

Yes. The derive-based structure in cli.rs supports adding variants to the Commands enum and corresponding Parser structs. The modular design maps each subcommand to its own implementation file, minimizing changes to core CLI logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}