# Where to Find Examples of Macro Usage: Official Docs, SDKs, and In-Repo Code Samples

> Discover Macro usage examples in official docs, Rust/TypeScript SDKs within the macro-inc/macro repo, and CLI samples for easy integration. Get started today!

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

---

**Macro provides official documentation at docs.macro.com, Rust and TypeScript SDK examples in `crates/` and `packages/`, and runnable CLI samples in `tooling/seed_cli`.**

Macro is an open-source productivity platform combining email, messaging, documents, and AI agents. Whether you're building integrations with the **Macro API** or experimenting with the SDKs, you'll find authoritative usage examples across three primary locations: the online product documentation, the repository's README, and concrete code samples embedded throughout the codebase according to the `macro-inc/macro` source code.

## Official Documentation and Quick-Start Links

The **entry point for all Macro examples** is the repository README, which aggregates links to product-specific documentation and SDK guides.

### README.md as the Central Hub

In [`README.md`](https://github.com/macro-inc/macro/blob/main/README.md), Macro maintains curated links to:

- **Product docs** for each core block: Email, Messages, Channels, Tasks, Docs, Agents, and CRM
- **SDK documentation** covering MCP (Model Context Protocol) integration and authentication flows
- **Quick-start guides** for getting a development environment running

This file lives at the repository root and serves as the authoritative starting point for developers asking **where to find examples of Macro usage**.

### Online Product Documentation

The full reference documentation at **https://docs.macro.com** contains the most extensive collection of usage examples. Each product block includes:

- REST and GraphQL payload examples
- SDK initialization patterns
- Authentication flow diagrams
- Code snippets for creating and linking entities

For instance, the [Email documentation](https://docs.macro.com/product/email) demonstrates how to compose messages, attach files, and leverage AI-powered drafting.

## In-Repo CLI Examples: tooling/seed_cli

For **runnable, real-world code**, the `tooling/seed_cli` directory provides a Rust-based CLI tool that seeds workspaces with test data. This is where you'll find concrete command patterns and JSON payload structures.

### seed_cli README and Test Files

| Location | What It Contains |
|----------|----------------|
| [`tooling/seed_cli/README.md`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/README.md) | Step-by-step tutorial for creating users, emails, documents, and channel messages |
| [`tooling/seed_cli/src/entity/user/test.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/entity/user/test.rs) | CLI examples for user creation |
| [`tooling/seed_cli/src/entity/document/test.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/entity/document/test.rs) | Document seeding with markdown content |
| [`tooling/seed_cli/src/entity/channel/test.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/entity/channel/test.rs) | Channel and message creation patterns |

These test files double as **minimal, verified examples** of how to structure API requests. The CLI commands map directly to the underlying REST endpoints, making them valuable reference implementations.

### Example: Seeding a Document via CLI

```bash

# From the repo root

cargo run --bin seed_cli document create \
  --owner "macro|alice@example.com" \
  --title "Project Plan" \
  --content "## Goals\n- ship MVP\n- gather feedback"

```

*Source:* [`tooling/seed_cli/src/entity/document/test.rs`](https://github.com/macro-inc/macro/blob/main/tooling/seed_cli/src/entity/document/test.rs)

The `--owner` prefix (`macro|`) denotes the provider namespace, a pattern you'll see consistently across Macro's entity linking system.

## Rust SDK Examples in crates/

Macro's core libraries live in `crates/`, with `macro_db_client` being the primary entry point for programmatic usage.

### Key Rust Client Files

| File | Purpose |
|------|---------|
| [`crates/macro_db_client/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/lib.rs) | Client initialization and configuration |
| [`crates/macro_db_client/src/user.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/user.rs) | `UserClient` with `create_user` and related methods |
| [`crates/macro_db_client/src/document.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/document.rs) | Document CRUD operations |
| [`crates/macro_db_client/src/message.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/message.rs) | Message and channel operations |

All Rust examples require an **MCP token** loaded via the `macro_env_var` crate or environment variables.

### Example: Creating a User with the Rust Client

```rust
use macro_db_client::user::UserClient;
use macro_env_var::env;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    // Load MCP token from environment (set via .env or Doppler)
    let token = env::var("MCP_TOKEN")?;
    let client = UserClient::new(&token);

    // Create a new user
    let user = client
        .create_user(&macro_db_client::user::CreateUser {
            email: "alice@example.com".into(),
            username: Some("alice".into()),
            ..Default::default()
        })
        .await?;

    println!("Created user: {}", user.id);
    Ok(())
}

```

*Source:* [`crates/macro_db_client/src/user.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/user.rs)

The `CreateUser` struct uses builder-style defaults, letting you specify only the fields you need while the SDK handles serialization and request signing.

## TypeScript SDK Examples in packages/

Frontend and Node.js developers should explore `packages/macro-client/`, which powers both the web client and Tauri desktop application.

### Key TypeScript Files

| File | Purpose |
|------|---------|
| [`packages/macro-client/src/index.ts`](https://github.com/macro-inc/macro/blob/main/packages/macro-client/src/index.ts) | Main export and client factory |
| [`packages/macro-client/src/channelMessages.ts`](https://github.com/macro-inc/macro/blob/main/packages/macro-client/src/channelMessages.ts) | Channel message creation and retrieval |
| [`packages/macro-client/src/documents.ts`](https://github.com/macro-inc/macro/blob/main/packages/macro-client/src/documents.ts) | Document API wrappers |
| [`packages/macro-client/src/auth.ts`](https://github.com/macro-inc/macro/blob/main/packages/macro-client/src/auth.ts) | Token management and refresh flows |

### Example: Creating a Channel Message

```typescript
import { MacroClient } from '@macro/client';

const client = new MacroClient({
  token: process.env.MCP_TOKEN!,   // MCP token from .env
});

async function postMessage() {
  const channelId = 'channel-123';
  const result = await client.channelMessages.create({
    channelId,
    senderId: 'macro|bob@example.com',
    content: 'Hey team, the latest build is live!',
  });
  console.log('Message ID:', result.id);
}

postMessage().catch(console.error);

```

*Source:* [`packages/macro-client/src/channelMessages.ts`](https://github.com/macro-inc/macro/blob/main/packages/macro-client/src/channelMessages.ts)

The TypeScript client mirrors the Rust client's structure, using the same entity ID conventions (`macro|{email}` format) and automatic `@link` relationship creation.

## How the Pieces Fit Together

Understanding **where to find examples of Macro usage** requires knowing how authentication, API surface, and entity relationships connect:

1. **Authentication** — All SDKs require an MCP token, generated via the web UI or CLI (`claude mcp add …`)
2. **API surface** — Public endpoints live under `/api/v1/…` with OpenAPI specs generated in-repo
3. **Entity creation** — `seed_cli` examples reveal exact JSON structures, identical across Rust and TypeScript clients
4. **Bidirectional linking** — SDKs automatically create `@link` relationships (e.g., linking a task to its originating email), demonstrated in the "linked markdown docs" examples

## Summary

- **docs.macro.com** — Most comprehensive examples for each product block (Email, Tasks, Agents, etc.)
- **`tooling/seed_cli/`** — Runnable CLI commands and test files showing real payload structures
- **`crates/macro_db_client/`** — Rust SDK with typed client functions in [`src/user.rs`](https://github.com/macro-inc/macro/blob/main/src/user.rs), [`src/document.rs`](https://github.com/macro-inc/macro/blob/main/src/document.rs), etc.
- **`packages/macro-client/`** — TypeScript SDK used by web and desktop apps
- **[`README.md`](https://github.com/macro-inc/macro/blob/main/README.md)** — Central hub linking all documentation and quick-start resources

## Frequently Asked Questions

### Where are the most complete Macro examples located?

The **online product documentation at https://docs.macro.com** contains the most extensive examples, with dedicated pages for Email, Messages, Tasks, Docs, Agents, and CRM. Each page includes REST/GraphQL payloads, SDK snippets, and authentication flow diagrams.

### Can I run the Macro examples without setting up a full environment?

Yes. The **`tooling/seed_cli`** provides standalone, runnable commands that work against any Macro workspace. Install the CLI with `cargo run --bin seed_cli`, set your `MCP_TOKEN` environment variable, and execute commands like `seed_cli user create` or `seed_cli document create` immediately.

### What is the difference between the Rust and TypeScript Macro SDKs?

Both SDKs wrap the same `/api/v1/` endpoints and use identical entity ID conventions. The **Rust client** (`crates/macro_db_client/`) offers typed async functions for backend services and CLI tools. The **TypeScript client** (`packages/macro-client/`) provides the same capabilities for frontend applications and Node.js scripts, with additional helpers for browser-specific concerns like token refresh.

### How do I authenticate with the Macro API in my own code?

All Macro SDKs require an **MCP token**. Generate one through the web UI under Settings → API Tokens, or via the CLI with `claude mcp add`. Pass this token to `UserClient::new()` in Rust or `new MacroClient({ token })` in TypeScript. The `macro_env_var` crate simplifies loading tokens from `.env` files or secret managers like Doppler.