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

> Explore the Macro CLI tool for streamlined dev, deploy, test, and run operations. This guide covers the `macro` binary and its subcommands for efficient development.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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.

```rust
// 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`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/Cargo.toml) under a `[[bin]]` section. This configuration produces the executable that users invoke:

```toml

# 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:**

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

```

**As an installed binary:**

```bash
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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/Cargo.toml)** — Declares the `macro` binary via the `[[bin]]` entry point.

- **[`tooling/xtask/crates/xtask_local/src/local/stack.rs`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/stack.rs), with orchestration wired through [`main.rs`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/crates/xtask_local/src/local/cli.rs). The binary entry point is [`tooling/xtask/crates/xtask_local/src/main.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/crates/xtask_local/src/main.rs), and supporting argument types are in [`tooling/xtask/crates/xtask_local/src/local/stack.rs`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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.