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

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 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.

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:

just run_local

Under the hood, this executes the run_local workflow (implemented in tooling/xtask/crates/xtask_workflows/src/workflows/run_local.rs), which runs:

docker compose -p macro up -d

The Docker Compose configuration at 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:

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:

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:

just preview

The preview workflow (defined in 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:

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:

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	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 and preview_fly.rs
docker/docker-compose.yml	Service orchestration for local development stack
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 handles stack startup, 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 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>.

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