Terminal CLI

Alumia ships an installable terminal package, @hasna/alumia, with one binary: alumia. The same credentials power the OpenTUI interactive agent, scriptable subcommands, local export/restore, and an MCP stdio server for Codex, Claude Desktop, and Gemini.

For hosted MCP over HTTP (https://app.alumia.com/mcp), see Connect via MCP. The stdio server exposed by alumia mcp --stdio is a separate, richer tool surface aimed at local automation.

Install

bun install -g @hasna/alumia

Configure

Run alumia or alumia login --device for first-run browser device login. The CLI prints an approval URL, waits for step-up approval in the browser, and stores the returned API key in ~/.alumia/config.json (mode 0600) without printing the secret.

alumia login --device
alumia login --device --base-url https://alumia.com
alumia login --profile prod --api-key "$ALUMIA_API_KEY" --base-url https://alumia.com --org my-org
alumia config list
alumia config use prod
alumia auth status
alumia whoami

Supported environment variables: ALUMIA_BASE_URL, ALUMIA_API_KEY, ALUMIA_ACCESS_TOKEN, ALUMIA_ORG, ALUMIA_WORKSPACE_ID, ALUMIA_AGENT_ID, ALUMIA_PROJECT_ID, ALUMIA_MODEL, ALUMIA_PROFILE, ALUMIA_CONFIG_PATH.

Device-login endpoints are rate-limited per IP. CLI device login and API key minting share the same token-bucket limits described in API access.

Interactive agent

Run alumia with no subcommand to open the OpenTUI terminal agent. Slash commands cover profiles, agents, projects, sessions, models, connectors, MCP install, files, apps, export/import, and diagnostics (/help, /doctor, /quit).

Normal prompt text streams through /api/v1/chat using the selected agent, project, session, and model.

Scriptable sessions and exec

alumia sessions list
alumia sessions new "Release triage" --project <project-id> --agent <agent-id>
alumia sessions messages <session-id> --page-size 25
alumia sessions resume <session-id> --connection <connection-id>
alumia exec "Summarize the active project" --project <project-id> --agent <agent-id>
alumia exec --json --wait-approval --permission-mode auto "Deploy the staging release"
alumia approve <tool-call-id> --session <session-id>

sessions resume calls the connector-auth resume API — pass --connection when retrying after OAuth completes. Use --wait-approval and --permission-mode auto|ask on exec for CI jobs that need guarded tool runs.

Org operations

First-class commands cover dashboard surfaces that previously required raw alumia api calls:

alumia billing summary|usage|catalog|budgets|buckets|ledger
alumia tasks list|create|get|update|delete
alumia schedules list|create|get|update|delete
alumia webhooks list|get|create|update|delete|rotate|events|deliveries
alumia memories list|nodes list|nodes get <id>
alumia knowledge list|search|collections|get <id>
alumia notifications list|mark-all-read|preferences
alumia recovery list|retry|resume
alumia secrets list|create|delete
alumia skills list|get <skill-id>
alumia blocks list|create|update|delete
alumia domains list|check|dns|verify
alumia telephony numbers
alumia contacts list
alumia agent-wallet summary|spend-requests|approve <id>
alumia dashboard overview
alumia agents get|sessions|messages|peers <id>
alumia projects update|delete|duplicate|export|restore <id>
alumia connections get|delete|oauth <connector>|test <id>
alumia mcp list|test|create|update|delete
alumia files list|get|download|upload|delete|patch|preview|finalize|presign
alumia apps list|get|preview|create|versions|install
alumia datasets list|get|download|export|create|delete|import

Browser-session and step-up gated mutations (agent config, skill install, workspace create, secret create, API key create) return 403 for API-key callers. The CLI surfaces the server error instead of pretending the action succeeded.

Most scriptable commands accept --format json|table|ndjson, --output-format json|table|ndjson, and --quiet. Use --output-format when a command already uses --format for a domain value such as export type.

Export and restore

alumia export project <project-id> --format filesystem --out ./exports/project
alumia export session <session-id> --format markdown --out ./exports/session.md
alumia import ./exports/session.json
alumia import ./exports/session.json --apply
alumia restore ./exports/app.json --apply --project <project-id>

Exports are redacted and include a SHA-256 checksum. Session imports can create a session and replay transcript messages. Project imports can create a project and restore exported canvas blocks. File and dataset imports are plan-only until the app exposes full content restore contracts.

MCP stdio server

alumia mcp --stdio
alumia mcp install --target codex
alumia mcp install --target claude
alumia mcp install --target gemini --dry-run
alumia mcp doctor

Stdio tools include alumia_exec, alumia_list_agents, alumia_list_projects, alumia_list_sessions, alumia_get_session_messages, alumia_export, alumia_list_models, alumia_list_connectors, alumia_list_mcp_servers, alumia_api_request, and alumia_import_plan. Use alumia_api_request for authenticated /api/v1 endpoints that do not yet have a dedicated tool.

Diagnostics

alumia doctor
alumia config
alumia api GET /agents
alumia completion zsh > ~/.zfunc/_alumia

alumia config masks saved tokens before printing. Do not paste raw API keys into issue reports, logs, or chat transcripts.