The CastHub CLI is a Python command-line tool for managing CastHub from the terminal, shell scripts, CI pipelines, or AI agents that cannot use MCP directly. It is a thin HTTP client over the CastHub REST API.

Prerequisites

An active CastHub account. The CLI does not create accounts. Sign up at https://dashboard.cast-hub.com/register-user.

The CLI requires Python 3.10 or later and uses JWT bearer authentication. Google and Microsoft sign-in are not available through the CLI. Use email and password.

Install

With pipx:

pipx install "git+https://github.com/Cast-Hub/CastHub.Backend.git#subdirectory=cli"

Or from source:

git clone https://github.com/Cast-Hub/CastHub.Backend.git
cd CastHub.Backend/cli
uv sync
uv run casthub --help

Authenticate

Sign in once per environment. Tokens are cached locally and refreshed automatically.

casthub login

You will be prompted for your email and password. Tokens are stored in ~/.casthub/credentials.json.

To verify your sign-in state:

casthub whoami

To sign out:

casthub logout

Environment switching

If you work across multiple environments, use the casthub-env wrapper. The wrapper sources ~/.casthub/<env>.env (which sets CASTHUB_API_URL) before running the CLI.

casthub-env dev login
casthub-env prod login
casthub-env dev presentations list --json
casthub-env prod device-groups get 5 --json

Common commands

casthub presentations list
casthub presentations get 42
casthub device-groups list
casthub device-groups get 5
casthub dashboard

All commands accept --json for machine-readable output.

Exit codes

Code	Meaning
0	Success
1	Generic error
2	Authentication error
3	Not found
4	Validation error

Use the CLI from AI agents

For AI agents and automation tools that cannot use MCP directly, the CLI provides a stable scripting interface. Pass --json on every command for machine-readable output, parse the JSON, and use the exit code to detect errors. Authentication is handled once at agent setup time through casthub login.

Full setup guidance for AI agent use is in the repository at cli/docs/ai-agent-setup.md.

Support

support@cast-hub.com