# How to Run Macro Commands: A Complete Guide to Development Workflows

> Learn how to run Macro commands easily using `just` and `xtask` for efficient development testing and deployment. Streamline your workflow today.

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

---

**Run Macro commands using `just` as the primary CLI driver, with recipes defined in the root `justfile` that delegate to the Rust-based `xtask` workflow engine for local development, testing, and deployment.**

The Macro repository is a large, multi-service Rust workspace that orchestrates document storage, email, search, and connection gateway services. Whether you're spinning up the full stack for local development or running a single service for fast iteration, all workflows are standardized through the `just` command runner. This guide covers every essential command and the underlying implementation in `macro-inc/macro`.

## Prerequisites: Understanding the Command Architecture

Macro uses a two-layer command architecture that keeps the developer experience simple while maintaining flexibility:

- **Layer 1:** The `justfile` at repository root provides memorable, short command names
- **Layer 2:** The `xtask` Rust binary in [`tooling/xtask/src/main.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/src/main.rs) parses arguments and dispatches to specialized workflows

All `just` commands automatically use the correct binary version through the repository's Nix environment at `nix/tauri-dev-shells.nix`. No global installation is required.

## Essential Macro Commands for Local Development

### Initialize the Development Environment

Before running any services, configure your local environment with databases, caches, and environment files.

```bash
just setup_dev

```

This command triggers the setup workflow in `tooling/xtask` that initializes PostgreSQL, Redis, OpenSearch, and other dependencies. It also creates the default `.env` files required by each service.

### Start the Full Service Stack

Launch every micro-service in Docker containers with a single command:

```bash
just run_local

```

Under the hood, this executes the `run_local` workflow (implemented in [`tooling/xtask/crates/xtask_workflows/src/workflows/run_local.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/crates/xtask_workflows/src/workflows/run_local.rs)), which runs:

```bash
docker compose -p macro up -d

```

The Docker Compose configuration at [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) declares all services including Postgres, Redis, OpenSearch, and S3-compatible storage.

### Run a Single Service for Targeted Development

When iterating on a specific crate, compile and launch only that service while keeping the rest of the stack running:

```bash
just run_email_service
just run_document_storage_service

```

These targets compile the service with `cargo build` (or `cargo x build`) and launch it within the local stack context. This approach significantly reduces rebuild times during focused development.

### Execute the Full Test Suite

Validate changes across all crates with comprehensive testing:

```bash
just test

```

This command runs:
- **Rust tests:** `cargo test` across all workspace crates
- **End-to-end tests:** Playwright tests located in `apps/web/tests/e2e` against the live database stack

## Deployment and Build Commands

### Deploy Pull Request Previews

Create dedicated preview environments for branch review:

```bash
just preview

```

The preview workflow (defined in [`tooling/xtask/crates/xtask_workflows/src/workflows/preview_fly.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/crates/xtask_workflows/src/workflows/preview_fly.rs)) deploys to `<branch>-<hash>-preview.macro.com` on Fly.io. This requires appropriate Fly.io access credentials.

### Build Production Artifacts

Generate release-ready packages for distribution:

```bash
just build          # Standard production build

just build-dmg      # Signed macOS installer

just build-appimage # Linux AppImage package

```

### Clean Up Development Resources

Stop containers and remove persistent volumes:

```bash
just stop_local   # Stop running containers

just clean_local  # Remove containers and volumes

```

## Key Implementation Files

Understanding these source files helps debug workflow issues and extend functionality:

| File | Purpose |
|------|---------|
| `justfile` | Root command definitions mapping `just <target>` to `xtask` invocations |
| [`tooling/xtask/src/main.rs`](https://github.com/macro-inc/macro/blob/main/tooling/xtask/src/main.rs) | CLI entry point that parses sub-commands and dispatches workflows |
| `tooling/xtask/crates/xtask_workflows/src/workflows/*.rs` | Individual workflow implementations including [`run_local.rs`](https://github.com/macro-inc/macro/blob/main/run_local.rs) and [`preview_fly.rs`](https://github.com/macro-inc/macro/blob/main/preview_fly.rs) |
| [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) | Service orchestration for local development stack |
| [`infra/stacks/web-app/README.md`](https://github.com/macro-inc/macro/blob/main/infra/stacks/web-app/README.md) | Web-app deployment pipeline documentation |

## Summary

- **Use `just` for all commands** — it's the standardized interface across the entire Macro workspace
- **Start with `just setup_dev`** — one-time initialization for databases, caches, and environment configuration
- **Run `just run_local`** — brings up the complete multi-service stack via Docker Compose
- **Target individual services** with `just run_<service_name>` for faster development cycles
- **Test everything** with `just test` before submitting changes
- **Deploy previews** using `just preview` for stakeholder review
- **Clean up** with `just stop_local` and `just clean_local` to recover disk space

## Frequently Asked Questions

### What is `just` and why does Macro use it?

**`just`** is a command runner that provides a Makefile-like interface with better ergonomics and cross-platform support. Macro uses it because recipes in the `justfile` are easier to read and maintain than shell scripts, and it integrates cleanly with the Rust-based `xtask` workflow system.

### How do I run commands without installing `just` globally?

The Macro repository pins `just` in its Nix environment at `nix/tauri-dev-shells.nix`. When you invoke `just` from the repository root (or use the provided Nix shell), it automatically uses the correct version without any global installation. Alternatively, you can run `cargo xtask <command>` directly since `xtask` is the underlying implementation.

### Where are the actual command implementations located?

Command implementations reside in `tooling/xtask/crates/xtask_workflows/src/workflows/*.rs`. Each `.rs` file corresponds to a major workflow: [`run_local.rs`](https://github.com/macro-inc/macro/blob/main/run_local.rs) handles stack startup, [`preview_fly.rs`](https://github.com/macro-inc/macro/blob/main/preview_fly.rs) manages PR deployments, and others cover testing, building, and cleanup operations. The root `justfile` provides the user-facing aliases that invoke these workflows.

### Can I modify the Docker Compose configuration for local testing?

Yes. The file at [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) defines all services and their dependencies. Modify this file to add environment variables, change port mappings, or inject local volumes. Run `just run_local` after modifications to apply changes. Note that some workflows may override specific settings through command-line flags passed to `docker compose`.

### How do I debug a failing `just` command?

Add the `--verbose` flag to see the underlying commands being executed: `just --verbose run_local`. For deeper inspection, examine the workflow source in `tooling/xtask/crates/xtask_workflows/src/workflows/` and run the `xtask` binary directly with `cargo run --bin xtask -- <workflow_name>`.