CLI | m8tes

Use the m8tes CLI to inspect agents, run tasks, manage app connections, and debug account state from your terminal.

Installation

Terminal

pip install -U "m8tes>=4.8"
m8tes auth login     # prompts for email + password, saves credentials locally

Or skip login and pass your API key directly: m8tes --api-key m8_your_key_here agent task "Do something".

Everyday commands

Terminal

m8tes agent task "Summarize the latest AI news"  # one-off task (auto-detects your agent)
m8tes agent chat                                 # interactive multi-turn conversation
m8tes agent list                                 # list agents
m8tes run list                                   # recent runs
m8tes run get 123                                # full run details

mate is a permanent alias (m8tes mate task … still works). Have more than one agent? Pass its id: m8tes agent task 7 "Prepare the weekly report". Inside a chat session use /exit, /clear, or /resume <run_id>; m8tes agent chat --resume 42 reopens a previous run.

Command reference

Auth

Terminal

m8tes auth status    # Check current login
m8tes auth logout    # Clear saved credentials
m8tes auth register  # Create a new account
m8tes auth usage     # Show plan limits and current usage
m8tes auth resend-verify

Tasks and output formats

Terminal

m8tes agent task "Do X" --output verbose  # Rich UI with tool calls (default)
m8tes agent task "Do X" --output compact  # Text-only output
m8tes agent task "Do X" --output json     # Raw event JSON
m8tes agent task "Do X" --debug           # Show event traces and counts

Reusable task definitions attach to agents and trigger manually, on a schedule, via webhook, or by email:

Terminal

m8tes task list                          # List all tasks
m8tes task list --mate-id 7              # Filter by agent
m8tes task get 42                        # Show task details
m8tes task create                        # Interactive creation wizard
m8tes task create --non-interactive \
  --mate-id 7 --name "Weekly Report" \
  --instructions "Generate metrics"      # Scripted creation
m8tes task execute 42                    # Run a saved task
m8tes task update 42 --name "New Name"   # Update task fields
m8tes task enable 42                     # Re-enable a disabled task
m8tes task disable 42                    # Disable a task
m8tes task archive 42                    # Archive a task

Agent management

Terminal

m8tes agent list                         # List all agents
m8tes agent list --include-disabled      # Include disabled agents
m8tes agent get 7                        # Show agent details
m8tes agent create                       # Interactive creation wizard
m8tes agent create --non-interactive \
  --name "Ops Bot" \
  --tools gmail slack \
  --instructions "Handle ops tasks"      # Scripted creation
m8tes agent update 7                     # Interactive update
m8tes agent update 7 --non-interactive \
  --name "New Name"                      # Scripted update
m8tes agent enable 7                     # Re-enable a disabled agent
m8tes agent disable 7                    # Soft-disable (preserves history)
m8tes agent archive 7                    # Archive (hidden from listings)

Run inspection

Terminal

m8tes run list                    # List recent runs
m8tes run list-mate 7             # Runs for a specific agent
m8tes run get 123                 # Full run details
m8tes run conversation 123        # View chat messages
m8tes run usage 123               # Token usage and costs
m8tes run set-permission-mode 123 approval
m8tes run tools 123               # Tool executions
m8tes run tools 123 --verbose     # With arguments and results
m8tes run audit-logs --limit 20   # API request audit logs
m8tes run audit-logs --method POST --resource-type run --status-code 201
m8tes run audit-logs --auth api_key   # only your SDK/API calls, not the web app's

set-permission-mode also works while a run is paused. Switching to autonomous resumes pending tool approvals, but AskUserQuestion still waits for runs.answer().

App connections

Terminal

m8tes apps list
m8tes apps list --user-id cust_123
m8tes apps connect-api-key gemini sk_live_123
m8tes apps connect-oauth gmail --redirect-uri https://yourapp.com/oauth/callback --user-id cust_123
m8tes apps connect-complete gmail conn_abc123 --user-id cust_123
m8tes apps disconnect gmail --user-id cust_123

Most commands have short aliases: m8tes m t "Do X" for agent task (m = agent alias), m8tes m ch for chat, m8tes r ls for run list, m8tes a l for auth login, m8tes task x for task execute.

Development Mode

Terminal

m8tes --dev agent task "Test locally"                             # targets http://127.0.0.1:8000
m8tes --base-url https://staging.m8tes.ai agent task "Staging"    # any backend

Override the local port with M8TES_PORT=9000.

CLI vs SDK

The CLI uses the same backend as the Python SDK. Choose based on your workflow:

	CLI	SDK
Best for	Quick tasks, debugging, exploration	Applications, automation, integrations
Auth	Email/password login	API key (`m8_`)
Streaming	Built-in terminal output	`RunStream` iterator

Next: Quickstart · Errors