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.49.0"
m8tes auth login     # prompts for email + password, saves credentials locally

For an API account, set M8TES_API_KEY and pass your end-user scope. New API accounts include $1 test credit for deepseek-v4-1-flash:

Terminal

export M8TES_API_KEY=m8_your_key_here
m8tes agent task "Say hello" --user-id hello_world --model deepseek-v4-1-flash

With --user-id and no agent ID, V2 finds or creates an agent in that scope. Pass an ID before the message to target an existing agent. This keeps strict scope checks enabled. Credentials resolve in this order: the global --api-key flag, M8TES_API_KEY, then your saved login. An explicit key never refreshes the saved login.

Agent and saved-task management commands also accept --user-id. Keep the same scope when inspecting or changing resources:

Terminal

m8tes agent list --user-id hello_world
m8tes agent get 7 --user-id hello_world
m8tes task list --user-id hello_world
m8tes task execute 42 --user-id hello_world
m8tes run list --user-id hello_world
m8tes run get 123 --user-id hello_world
m8tes run list-agent 7 --user-id hello_world

Replace the example IDs with your own. The command reference below uses account-level examples; append --user-id for tenant-scoped resources wherever supported. Run conversation, usage, tools, and retry commands resolve the existing run directly.

agent chat accepts the same --user-id and --model flags for existing agents. Scope applies to agent selection and resume validation; replies inherit the existing run's scope and model. --model applies to new runs only, including after /clear.

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 --agent-id 7              # Filter by agent
m8tes task get 42                        # Show task details
m8tes task create                        # Interactive creation wizard
m8tes task create --non-interactive \
  --agent-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

Tools are optional. Use app IDs from m8tes apps list when adding integrations (for example gmail or slack).

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