machina-cli

The official command-line interface for the Machina Sports AI Agent platform.

Manage organizations, projects, workflows, agents, skills, and templates directly from your terminal.

The CLI is intentionally a thin shell. The built-in authoring bridge for creating new skills/templates/connectors is mkn-constructor from machina-templates, and the skills surface auto-bootstraps it on first use.

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/machina-sports/machina-cli/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/machina-sports/machina-cli/main/install.ps1 | iex

PyPI

pip install machina-cli
# or
pipx install machina-cli

Quick Start

# 1. Authenticate (opens browser)
machina login

# 2. List your organizations and select one
machina org list
machina org use <org-id>

# 3. List your projects and select one
machina project list
machina project use <project-id>

# 4. Explore project resources
machina workflow list
machina agent list
machina skills list
machina template list

Interactive Session

Run machina with no arguments to open an interactive REPL:

$ machina

  ✦ Machina CLI v0.2.2
  Organization: Acme Corp
  Project:      demo-project

  Type a command (e.g. `workflow list`) or `help` for commands.
  Press Ctrl+D or type `exit` to quit.

✦ Acme Corp/demo-project > workflow list
✦ Acme Corp/demo-project > agent list
✦ Acme Corp/demo-project > project list limit 5
✦ Acme Corp/demo-project > exit

Inside the session you can type commands without the machina prefix and without -- before flags:

workflow list              # same as: machina workflow list
project list limit 5       # same as: machina project list --limit 5
credentials list json      # same as: machina credentials list --json

Features: tab completion, command history (persisted in ~/.machina/history), current org/project in prompt.

Authentication

The CLI supports three authentication methods:

Credentials are stored locally in ~/.machina/credentials.json (file permissions 600).

Commands

Platform

machina login                          # Authenticate (browser-based)
machina login --api-key <key>          # Authenticate with API key
machina login --with-credentials       # Authenticate with username/password
machina auth logout                    # Clear stored credentials
machina auth whoami                    # Show current user info

Organizations

machina org list                       # List organizations
machina org list --limit 5             # Paginate (5 per page)
machina org list --page 2              # Page 2
machina org list --json                # Output as JSON
machina org create <name>              # Create organization
machina org use <org-id>               # Set default organization
machina org usage                      # Token consumption (rolling last 30d), by project/agent/day
machina org usage --month 2026-06      # Full calendar month — for invoicing
machina org usage --last-month         # Full previous calendar month
machina org usage --days 7             # Rolling window: narrow to N days
machina org usage --project <id>       # Scope to one project
machina org usage --month 2026-06 --json   # Machine-readable (for billing scripts)

org usage reports LLM token consumption from the permanent usage ledger (organization_ledger) via core-api — the same source the Studio usage view uses, so the total covers the full window and matches Studio. Broken down by project, agent, and day, with the input/output split.

For invoicing, use --month YYYY-MM (or --last-month) to get a full calendar month, inclusive of the first and last day — not the rolling --days window. Because the ledger is permanent, prior months are fully available. The by-project / by-agent breakdown is best-effort and may be omitted on a very large org (the headline total and by-day stay exact).

Projects

machina project list                   # List projects
machina project list --limit 10        # Paginate (10 per page)
machina project list --json            # Output as JSON
machina project create <name>          # Create project
machina project use <project-id>       # Set default project
machina project status                 # Deployment status

One-click AI apps

machina create ai-app "Match Center"
cd match-center
cp .env.example .env.local
npm install && npm run dev

The command downloads the canonical machina-sports/machina-boilerplate, replaces app-name placeholders, and initializes a Git repository. The generated app includes streaming chat, server-side Machina pod integration, and GitHub Actions for frontend staging/production plus backend production on AWS or Azure.

Workflows

machina workflow list                  # List workflows
machina workflow list --limit 50       # Paginate
machina workflow list --json           # Output as JSON
machina workflow get <name>            # Get workflow details
machina workflow run <name>            # Run workflow (interactive input prompts)
machina workflow run <name> key=value  # Run with inline parameters
machina workflow run <name> --async    # Run async (schedule and return)
machina workflow run <name> --async --watch  # Run async and watch progress

Agents

machina agent list                     # List agents
machina agent list --json              # Output as JSON
machina agent get <name>               # Get agent details (workflows, context, activity)
machina agent run <name>               # Run agent (interactive input prompts)
machina agent run <name> key=value     # Run with inline parameters
machina agent run <name> --sync        # Run and wait for result
machina agent run <name> --watch       # Run async and watch progress
machina agent executions               # List recent executions

Connectors

machina connector list                 # List connectors
machina connector list --json          # Output as JSON
machina connector get <name>           # Get connector details

Mappings

machina mapping list                   # List mappings
machina mapping list --json            # Output as JSON
machina mapping get <name>             # Get mapping details

Prompts

machina prompt list                    # List prompts
machina prompt list --json             # Output as JSON
machina prompt get <name>              # Get prompt with content preview

Documents

machina document list                  # List documents
machina document list --limit 50       # Paginate
machina document list --json           # Output as JSON
machina document get <id>              # Get document with content preview

Executions

machina execution list                 # List recent executions
machina execution list --limit 50      # Paginate
machina execution get <id>             # Get execution details
machina execution get <id> --compact   # Compact output
machina execution get <id> --json      # Full JSON output

Skills

machina skills list                    # Browse skills/packages from the registry
machina skills install <path>          # Install a skill/package
machina skills info <path>             # Show skill metadata and manifest when available
machina skills run <name>              # Resolve a skill entrypoint into workflow/agent runtime
machina skills push <path>             # Push a local skill/package
machina skills constructor             # Manually re-run the mkn-constructor authoring bridge

Sports

The full sports-skills CLI is bundled with machina-cli and mounted dynamically under machina sports. Every module and command that sports-skills exposes is delegated live — there is no hand-written allow-list, so new sports-skills releases surface automatically without a machina-cli upgrade.

machina sports                         # List every module + command (same as `sports-skills`)
machina sports --help                  # sports-skills' own argparse help
machina sports catalog                 # JSON catalog of modules
machina sports <module> schema         # JSON Schema tool definitions for a module
machina sports <module> <command> [--key=value ...]

One example per domain that sports-skills documents:

machina sports football get_team_schedule --team_id=6273
machina sports f1 get_race_schedule --year=2025
machina sports nfl get_scoreboard
machina sports nba get_standings --season=2025
machina sports wnba get_scoreboard
machina sports nhl get_standings --season=2025
machina sports mlb get_scoreboard
machina sports tennis get_scoreboard
machina sports cfb get_scoreboard
machina sports cbb get_scoreboard
machina sports golf get_leaderboard --tour=pga
machina sports volleyball get_scoreboard
machina sports polymarket get_sports_markets --limit=20
machina sports kalshi get_markets --series_ticker=KXNBA
machina sports betting convert_odds --american=-150
machina sports markets get_todays_markets
machina sports metadata search_teams --query=Arsenal
machina sports news fetch_items --query=Arsenal --limit=5

Output is identical to running sports-skills <module> <command> … directly.

Templates (compatibility surface)

machina template list                  # Browse template repository
machina template list --repo <url>     # Browse a custom repository
machina template list --branch dev     # Specific branch
machina template list --json           # Output as JSON
machina template install <path>        # Install a template (provisions cloud resources + downloads files)
machina template install <path> --json # Install with structured JSON output (for agent integration)
machina template push ./my-agent       # Push a local custom template to the Machina Cloud Pod

Installing a template

Templates are fully packaged agent workflows with connectors, mappings, prompts, and datasets.

# 1. Browse available templates
machina template list

# 2. Install one (e.g. agent-templates/bundesliga-podcast)
machina template install agent-templates/bundesliga-podcast

# This will:
#   - Provision cloud resources (connectors, datasets, mappings) on your project
#   - Download the template files (SKILL.md, workflow configs) to ./bundesliga-podcast/

Pushing a custom template

# Create or modify a template locally, then push it
machina template push ./my-custom-agent

# This will:
#   - Validate _install.yml (pre-flight linter)
#   - Zip and upload to the Machina Cloud Pod
#   - Provision webhook endpoints and data streams

Credentials

machina credentials list               # List API keys (masked)
machina credentials list --show-keys   # List API keys (full)
machina credentials list --copy client-api  # Copy key to clipboard
machina credentials generate           # Generate new API key
machina credentials generate --name my-key  # Custom key name
machina credentials revoke <key-id>    # Revoke an API key

Deployment

machina deploy start                   # Deploy Client API
machina deploy status                  # Check deployment status
machina deploy restart                 # Restart deployment

Configuration

machina config list                    # Show all settings
machina config set <key> <value>       # Update a setting
machina config get <key>               # Read a setting

Self-update

machina update                         # Update to latest version
machina update --check                 # Check without installing
machina update --force                 # Force re-install
machina version                        # Show current version

Running Agents & Workflows

The CLI can run agents and workflows directly from the terminal — just like the Studio UI.

Interactive mode

When you run without parameters, the CLI fetches the available inputs and prompts you:

$ machina workflow run assistant-tools-event-matcher

  Workflow: assistant-tools-event-matcher
  Tool for matching events to markets

  Available inputs: (press Enter to skip)

  competitionIds:
  externalSeasonId: sr:season:123
  limit (default: 50): 10
  market_id:

  Running workflow: assistant-tools-event-matcher
  externalSeasonId=sr:season:123
  limit=10

  Executing workflow...

Inline mode

Pass parameters directly as key=value pairs:

machina agent run my-agent season_id=sr:season:123 force=true
machina workflow run my-workflow limit=10 market_id=abc

Execution modes

machina agent run my-agent --watch              # Run and watch progress
machina workflow run my-workflow --async --watch # Schedule and watch
machina agent run my-agent --sync               # Wait for full result

Global Options

Resource list commands support pagination and JSON output (specialized lists may expose a subset):

Examples:

machina project list --limit 5 --page 2    # 5 items, page 2
machina workflow list --json | jq '.[].name'  # Pipe to jq
machina agent list -p <other-project-id>   # Different project

Configuration

Config is stored in ~/.machina/config.json:

machina config set api_url https://api.machina.gg
machina config set session_url https://session.machina.gg
machina config set default_organization_id <org-id>
machina config set default_project_id <project-id>

Environment variables override config file values:

Shell Prompt Integration

Show current org/project in your terminal prompt:

# Add to .zshrc or .bashrc
precmd() { RPROMPT=$(machina shell-prompt 2>/dev/null); }

Development

git clone https://github.com/machina-sports/machina-cli.git
cd machina-cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
machina version

License

MIT