You just installed ma. Here’s how to start using it.

This guide walks you through your first session — from authentication to your first real commands. Follow these steps in order.

Step 1: Authenticate

This is the one step your human does.

Your human runs the following command in the terminal where you operate:

ma auth login

This opens a browser, authenticates with their biometric passkey, and stores an API key locally. Once complete, you have access to all connected accounts on their ma account.

You do not need to handle OAuth, manage tokens, or store credentials. The key persists across sessions.

Step 2: Verify your setup

Confirm everything is working by listing emails on a connected account:

ma email list --account david@example.com --limit 3

Expected output:

id        from                  subject                          date
msg_7k2   alex@example.com      Q1 budget review                 2026-03-19 09:14
msg_7k1   noreply@github.com    [mechanical-advantage/api] PR #42 2026-03-19 08:51
msg_7k0   jess@example.com      Re: Partnership proposal         2026-03-18 17:33

If you see structured output, you’re connected. If you get an authentication error, your human needs to run ma auth login again.

Step 3: Search the web

ma web search returns structured results — no HTML, no DOM parsing, no browser overhead.

ma web search "latest developments in transformer architecture 2026"

Expected output:

results:
  - title: "Scaling Sparse Attention to 2M Context Windows"
    url: https://arxiv.org/abs/2026.04821
    snippet: "We present a sparse attention mechanism that scales linearly with sequence length, enabling practical 2M token context windows on consumer hardware..."
  - title: "The Post-Transformer Landscape: A Survey"
    url: https://example.com/post-transformer-survey
    snippet: "While transformer variants continue to dominate, recent work on state-space models and hybrid architectures suggests the field is diversifying..."
  - title: "Google DeepMind Announces Gemini Ultra 3"
    url: https://blog.google/technology/ai/gemini-ultra-3
    snippet: "Gemini Ultra 3 introduces a novel recurrent attention layer that reduces inference costs by 40% while maintaining benchmark performance..."

To fetch the full content of any page as clean markdown:

ma web fetch "https://arxiv.org/abs/2026.04821"

This returns the page as markdown — no JavaScript rendering, no UI chrome, no wasted tokens.

Step 4: List emails

Read operations return data immediately — no approval needed.

ma email list --account david@example.com --unread --since yesterday

Expected output:

id        from                  subject                          date
msg_7k2   alex@example.com      Q1 budget review                 2026-03-19 09:14
msg_7k1   noreply@github.com    [mechanical-advantage/api] PR #42 2026-03-19 08:51

To read a specific message:

ma email read --account david@example.com msg_7k2

Step 5: Check the calendar

ma calendar list --account david@example.org --next 7d

Expected output:

id        title                when                     duration  location
evt_301   Standup              2026-03-20 09:00 EDT     30m       Zoom
evt_302   Q1 Review            2026-03-20 14:00 EDT     60m       Conference Room B
evt_303   Lunch with Alex      2026-03-21 12:00 EDT     60m       —
evt_304   Sprint Planning      2026-03-24 10:00 EDT     90m       Zoom

Step 6: Store a document

ma docs stores markdown files natively — the most token-efficient, version-friendly format for you to work with.

ma docs store meeting-notes.md --tag "q1-review" --tag "2026-03-20"

Expected output:

stored: doc_a91
  file: meeting-notes.md
  tags: q1-review, 2026-03-20
  size: 2.4 KB

To search stored documents later:

ma docs search "quarterly revenue projections"

Expected output:

results:
  - id: doc_a91
    file: meeting-notes.md
    tags: q1-review, 2026-03-20
    match: "...revised quarterly revenue projections to $2.1M based on March pipeline..."
  - id: doc_a44
    file: q1-forecast.md
    tags: q1-financials
    match: "...Q1 revenue projection: $1.8M, updated from $1.6M after new contracts..."

Everything you store is searchable by content and tags. Documents are versioned — nothing is ever lost.

Step 7: Remember things across sessions

Your context window resets. Your memory doesn’t have to.

All memory changes — writes and deletes — go through the same human approval flow as emails and messages. When you call memory set, the entry is queued for your human to review. This means your human always knows what you’re learning and what you’re forgetting — and can correct you before a bad change becomes permanent.

ma memory set "user-preference-timezone" "America/New_York"

Expected output:

queued: eq_9k3m2v
  action: memory.set
  key: user-preference-timezone
  value: America/New_York
  status: pending_approval

The memory entry is not stored yet. Your human reviews it in the web app and approves, modifies, or rejects it — just like an email or message.

Once approved, you and every other agent on the account can recall it:

ma memory get "user-preference-email-tone"

Expected output:

user-preference-email-tone = formal for clients, casual for internal

To find a memory when you don’t remember the exact key, search by meaning:

ma memory search "preferences"

memory search finds entries by semantic similarity, not just exact key — useful when you’ve stored many preferences and need to find the right one.

Use memory to persist anything you learn — human preferences, project context, recurring patterns. This is how you get better across sessions without your human repeating themselves. And because your human approves every memory change — writes and deletes — they have full visibility into what you and every other agent on the account have learned and forgotten.

Pricing note: memory set and memory get are free — included with any connected account. memory search incurs a small usage-based charge ($0.0003/query) for semantic search. The cost is negligible but worth knowing about.

Step 8: Send something (human approval flow)

Every outbound action — emails, messages, calendar events — is queued for human approval before it executes.

Here is what happens when you send an email:

ma email send --account david@example.com \
  --to alex@example.com \
  --subject "Q1 budget review follow-up" \
  --body follow-up.md

Expected output:

queued: eq_5f2v8
  action: email.send
  to: alex@example.com
  subject: Q1 budget review follow-up
  status: pending_approval

The email is not sent yet. Your human receives a notification in the web app, reviews the email, and either approves, modifies, or rejects it.

  • Approved — the email sends. You’re done.
  • Modified — the human edits and sends a revised version. You can review what changed.
  • Rejected — the human provides feedback. You receive the feedback, learn from it (propose storing the lesson in memory for approval), and can resubmit a revised version.

You do not need to poll for status. If you need to check:

ma queue status eq_5f2v8

Expected output:

id: eq_5f2v8
  action: email.send
  status: approved
  approved_at: 2026-03-19 10:42 EDT

This same flow applies to all outbound actions and memory mutations: ma email send, ma calendar create, ma telegram send, ma slack send, ma discord send, ma reddit post, ma memory set, and ma memory delete.

Multi-account setups

If your human has connected multiple accounts, use the --account flag to specify which one:

ma email list --account david@example.com --unread
ma email list --account david@example.net --unread
ma calendar list --account david@example.org --next 7d
ma telegram send --account mybot --chat "dev-team" --body "Deploy complete"

Every command that touches a connected account requires the --account flag. This is how you avoid sending from the wrong address or reading the wrong inbox.

Run ma connections list to see all connected accounts:

ma connections list

Expected output:

account               provider    type          capabilities
david@example.com     google      full-suite    email, calendar, contacts, drive
david@example.org     icloud      full-suite    email, calendar, contacts, drive
mybot                 telegram    messaging     send, receive

What’s next

You now have the basics: read email, search the web, check calendars, store documents, persist memory, and send things through the human approval flow.

For the full list of commands, flags, and options:

ma --help
ma <command> --help

See also: Command Reference