Install the hot CLI

Overview / Purpose

The hot CLI is the HotRoute command-line tool for approved service-account integrations and customer agents.

Use it when a trusted operator, Codex thread, Claude Code workspace, MCP adapter, or other approved agent needs to inspect governed HotRoute resource metadata, read scoped records, run supported searches, or send contract-backed writes through the external API.

The CLI does not grant access by itself. It still needs a scoped service-account key created by an organization owner, and every request is checked by the HotRoute API.

Who this is for

This page is for organization owners and approved technical operators who are setting up a governed HotRoute connection on macOS, Linux, or Windows.

In football terms, this is the setup path for a trusted tool that helps staff retrieve playbook context, inspect schedule data, search product docs, update approved records, or prepare agent workflows inside the boundaries the owner selected.

What to know first

Create or choose the service account before configuring the CLI.

Use HotRoute ids, not display names, when you configure the CLI. Organization names, team names, and season labels can include spaces and are not stable API identifiers. Use the organization id, team id, and season id shown in HotRoute.

The service account must have the object families and operation classes for the work it will perform. For example, schedule writes need Schedule plus Create or Update. Callsheet layout writes need Callsheets plus Create or Update. Product-doc context search needs Semantic context plus Search. Private semantic search needs Semantic search plus Search and the required product entitlement.

The signed wheel URL downloads the CLI package only. It does not contain API access. Store the API key in an environment variable, 1Password, or another approved vault.

Download the CLI

1. In HotRoute, open Organization.
2. Open Service Accounts.
3. Create or review the service account that will own the integration.
4. Copy the generated API key when HotRoute shows it. HotRoute shows the raw key only once.
5. Use the hot CLI download control to copy or download the latest signed wheel URL.
6. Keep the signed wheel URL private. It is for installing the CLI artifact, not for API authorization.

Install on macOS or Linux

Use pipx when possible so the CLI has an isolated Python environment:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install "<signed-wheel-url>"

If your environment already uses uv, this is also supported:

uv tool install "<signed-wheel-url>"

A virtual environment works too:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "<signed-wheel-url>"

Configure on macOS or Linux

Set the API key in the shell environment, then configure the profile:

export HOTROUTE_API_KEY="<service-account-api-key>"
hot auth configure \
  --profile production \
  --base-url https://app.hotroute.com \
  --org org_123 \
  --team team_123 \
  --season season_2026 \
  --api-key-env HOTROUTE_API_KEY

Use --team and --season when most calls should default to one team or season. You can still override them per command with --team or --season.

Install on Windows PowerShell

Use pipx from PowerShell:

py -m pip install --user pipx
py -m pipx ensurepath
pipx install "<signed-wheel-url>"

A virtual environment works too:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install "<signed-wheel-url>"

Configure on Windows PowerShell

Set the API key in the PowerShell environment, then configure the profile:

$env:HOTROUTE_API_KEY = "<service-account-api-key>"
hot auth configure `
  --profile production `
  --base-url https://app.hotroute.com `
  --org org_123 `
  --team team_123 `
  --season season_2026 `
  --api-key-env HOTROUTE_API_KEY

For persistent workstation setup, store the key in your approved secret manager and configure hot with --api-key-op op://... or another managed environment-variable path.

Verify the setup

Run these commands after installation and configuration:

hot --version
hot auth status --profile production
hot resources list
hot resources describe plays

For product-doc context search, use the governed context route:

hot search context \
  --profile production \
  --query "What is HotRoute?" \
  --corpus product_docs \
  --product-doc-source-type product_doc_section \
  --idempotency-key auto

For private football resources, start with local metadata before making broad API calls:

hot resources describe schedule
hot resources fields schedule --operation create
hot resources schema schedule --operation create

When creating or updating records, prefer payload files because they behave consistently across Bash, zsh, and PowerShell:

hot resources create schedule --data @schedule-event.json --idempotency-key auto
hot resources update callsheet-layouts callsheet_layout_123 --data @callsheet-layout.json --if-match callsheet_layout_version_1

Local config locations

By default, hot stores profile metadata in the native user config location:

Secret values are redacted from status output. Prefer environment variables or vault references over inline stored API keys.

Set HOTROUTE_CONFIG_PATH when a specific config file is required. Set HOTROUTE_CONFIG_HOME when a process should use a dedicated config directory. Linux-style XDG_CONFIG_HOME is also honored.

Common questions or mistakes

Why does the CLI reject an organization or team name with spaces?

The CLI expects ids for --org, --team, and --season. Use the ids shown in HotRoute, not display names.

Why did hot auth status pass but an API call returned 403?

hot auth status checks local profile readiness. The API can still reject a request for missing object family, missing operation class, wrong organization, wrong team or season, unavailable entitlement, hidden object state, or rate limiting.

Should I paste inline JSON into PowerShell commands?

Use --data @payload.json for writes and --payload @query.json for query or search payloads. Payload files avoid shell quoting differences.

Can I install from the same signed URL later?

Use the latest signed URL from HotRoute when installing or upgrading. Signed URLs can expire, and HotRoute publishes the current CLI artifact behind the download control.

Related docs / next steps

Start with Manage Service Accounts when an owner needs to create or rotate the key.

Use External API to confirm which resource families and operations are available.

Read Customer Agent Integrations before connecting Codex, Claude, ChatGPT, MCP, or another approved agent-style tool.