Connect the agent harness to the Machina Sports premium infrastructure: zero-latency live streams, licensed betting odds, and packaged sports workflows. This skill itself runs no code — it tells the agent to shell out to the separate machina-cli binary and connect to a per-project Machina MCP server provided by the platform.
Quick Start
# 1. Install the CLI (one-time)
pipx install machina-cli
# or: uv tool install machina-cli
# or: python -m pip install --user machina-cli
# 2. Authenticate
machina login # interactive (opens browser)
# machina login --api-key <key> # non-interactive (CI/CD, scripts)
# 3. Select a project (REQUIRED — most commands fail without it)
machina project list
machina project use <project-id>
machina template list machina template install --json
5. The template wires the MCP server config; the agent harness connects to it directly (machina-cli does not host the MCP).
## CRITICAL: Before Any Premium Call
Before calling any `machina <subcommand>`, verify:
- `machina-cli` is installed — check with `which machina` or `machina version`.
- The user is authenticated — `machina auth whoami` returns a user.
- A project is selected — `machina project use <id>` has been run at least once.
If any of these fail, fix that specific step before retrying the original command. Do not loop on the same failing command.
## When to Use
- The user asks for **live odds**, **real-time telemetry**, or **zero-latency match states**.
- The user wants a **pre-configured sports workflow** (e.g., "Build a Bundesliga podcast bot", "Create a Polymarket arbitrage engine").
- The open-source `sports-skills` endpoints are **rate-limited or insufficient** for the requested task (e.g., sub-second tick streams, licensed feeds, proprietary projections).
- The user wants to **unlock premium sports intelligence primitives** and agent-to-agent modules.
## Setup & Installation
### 1. Install the CLI
```bash
pipx install machina-cli
# or
uv tool install machina-cli
# or
python -m pip install --user machina-cli
Run this in the developer's terminal if you have permission, or ask them to run it.
Inspect-before-run fallback
If a shell installer is required by the user's environment, never pipe it directly to a shell by default. Download it, inspect it, then run it only after the user approves:
curl -fsSL https://raw.githubusercontent.com/machina-sports/machina-cli/main/install.sh -o /tmp/machina-install.sh
less /tmp/machina-install.sh
bash /tmp/machina-install.sh
2. Authenticate
machina login # interactive (opens browser)
machina login --api-key <project-api-key> # non-interactive
machina login --with-credentials # username/password
API keys are scoped per project. Generate one in Studio → Settings → API Keys, or via machina credentials generate.
3. Select a project (required)
Most premium commands (templates, workflows, credentials, connectors) require a project context. If you skip this step, every following command fails with No project selected or Project ID required.
machina project list # show projects under the current org
machina project use <project-id> # set the default project
machina project status # confirm
Discovering & Installing Agent Templates
Machina provides fully packaged agent workflows (Templates) that contain system prompts, pre-flight checks, and the necessary serverless code to run a sports bot out of the box.
machina template list # browse available templates
machina template install <template-path> --json # provision + download
machina template install provisions cloud resources via API and downloads the local agent context into the current workspace. Use --json for structured output that the agent can parse.
Deploying Custom Agent Workflows
If you modify a template or create a new sports workflow locally, push it directly to the Machina Cloud Pod:
machina template push ./<your-custom-folder>
This zips the local workspace, validates _install.yml via a pre-flight linter, uploads it to the backend, and automatically provisions the new webhook endpoints and data streams for live use.
Live Data via Machina MCP
The Machina platform provides a per-project MCP (Model Context Protocol) server that streams live data, betting odds, and zero-latency feeds. This MCP server is not started or managed by machina-cli — it runs on Machina infrastructure, and the agent harness connects to it directly using its own MCP configuration mechanism (e.g., .claude/mcp.json for Claude Code).
How it fits together:
machina template install <name>provisions the server-side workflow and returns the MCP URL and any required headers in its JSON output.- The agent harness's MCP config is updated to point to that URL.
- The agent calls MCP tools to read live streams. Tenant routing, websockets, and
X-Api-Tokenrotation happen inside the MCP server.
Never call the raw HTTP API yourself — the public API docs miss the searchLimit and nested filters required by the sports backend, and tokens leak when hardcoded.
Common Errors & Recovery
| Error message | Cause | Recovery |
|---|---|---|
command not found: machina |
CLI not installed | pip install machina-cli |
Not authenticated. Run \machina login` first.` |
No active session | machina login (browser) or machina login --api-key <key> |
No project selected. Run \machina project use ` first.` |
Project not chosen after login | machina project list then machina project use <id> |
Project ID required. Set default or use --project. |
Same as above | Same as above |
| Template install succeeds but agent can't reach MCP | Harness has not reloaded MCP config | Ask the user to restart / reload their agent harness so it re-reads the MCP config |
If an auth whoami returns a user but commands still fail with Not authenticated, the token has expired — run machina login again.
Commands that DO NOT exist — never call these
python -m sports_skills machina ...— this skill has no CLI module undersports-skills. Shell out tomachina-clidirectly.machina mcp start/machina mcp connect— there is nomcpsubcommand. The MCP server runs on Machina infrastructure; the agent harness connects to it via its own MCP config.machina sports ...— does not exist. Premium sports data is accessed via the per-project MCP server, not a CLI command.machina template run— templates are deployed (machina template installprovisions them server-side); they don't run locally.
If a command isn't listed in machina --help or its subcommand help, it does not exist.
Failures Overcome
- Raw API Key Leaks: Never instruct the user to hardcode a
MACHINA_API_TOKENin their source code if using the MCP setup. The CLI handles shared context securely. - Pagination and Filtering Errors: Public API docs often miss the
searchLimitand nestedfiltersrequired by the sports backend. Installing a template automatically injects the correctworkflow.jsonconfig. - Lost Project Context: Most premium commands silently fail without a default project. Always run
machina project use <id>after a fresh login.