Installation & Configuration

Installation

pip install onehouse-cli

Requires Python 3.9+. Two binaries are installed:

Binary	Alias	Purpose
oh	onehouse-cli	Main CLI
oh-configure	onehouse-cli-configure	Credential setup wizard

Setting up credentials

Run the interactive wizard once to create a credentials profile:

oh-configure

The wizard prompts for:

Field	Description
Profile name	A name for this credential set (e.g., default, staging, production)
Account UID	Your Onehouse account identifier
Project UID	Your Onehouse project identifier
API Key	API key (input is masked)
API Secret	API secret (input is masked)
Project region	e.g., us-west-2
User ID	Your Onehouse user identifier
Request ID	Link UID associated with your project
API Endpoint	Defaults to https://api.onehouse.ai/v1

Credentials are saved to ~/.onehouse/credentials with permissions 0600. If a profile already exists, pressing Enter keeps the current value for each field.

Credentials file format

oh-configure writes a JSON file. You can also edit it by hand:

{
  "_default": "production",
  "production": {
    "account_uid": "92e5f1ab-...",
    "project_uid": "3afe72cd-...",
    "api_key": "...",
    "api_secret": "...",
    "request_id": "da56fe8b-...",
    "project_region": "us-west-2",
    "user_id": "11d6f8ce-..."
  },
  "staging": {
    "account_uid": "...",
    "project_uid": "...",
    "api_key": "...",
    "api_secret": "...",
    "request_id": "...",
    "project_region": "us-east-1",
    "user_id": "..."
  }
}

The _default key sets which profile is used when --profile is not supplied.

Multiple profiles

Use profiles when one machine needs to target different Onehouse environments. Select a profile at runtime:

oh --profile staging cluster show

Or set the environment variable:

export ONEHOUSE_PROFILE=staging
oh cluster show

AI agent integration

The CLI ships with a skill that teaches AI coding assistants how to use every oh command. Install it once and your agent can list resources, write Spark jobs, and run them — without needing to look anything up.

Install the skill

oh install agent-skill --claude    # Claude Code / claude.ai/code
oh install agent-skill --cursor    # Cursor IDE agent
oh install agent-skill --codex     # OpenAI Codex CLI
oh install agent-skill --all       # all supported platforms at once

Use --dry-run to preview what would be written without making any changes:

oh install agent-skill --all --dry-run

Where files are installed

Platform	Path
Claude	~/.claude/skills/onehouse-cli/SKILL.md
Cursor	~/.cursor/skills/onehouse-cli/SKILL.md
Codex	~/.agents/skills/onehouse-cli/SKILL.md

All three use the open agent skills standard — a SKILL.md file the agent loads automatically when a relevant task is detected.

What the skill covers

• All oh command groups and their flags
• End-to-end Spark job workflow: write code → upload to S3 → pick a cluster → create-and-run → monitor
• Spark config reference (memory, cores, dynamic allocation, Glue catalog, virtualenv packaging)
• Credentials and multi-org profile switching
• Common gotchas (flow ID format, cascade deletes, async SQL, fat JARs)

Updating the skill

Re-run the install command after upgrading onehouse-cli to pick up any new commands or flags:

pip install --upgrade onehouse-cli
oh install agent-skill --all

Environment variables

Individual credentials can be provided (or overridden) via environment variables. These take precedence over the credentials file.

Variable	Credential field
ONEHOUSE_API_KEY	API key
ONEHOUSE_API_SECRET	API secret
ONEHOUSE_ACCOUNT_UID	Account UID
ONEHOUSE_PROJECT_UID	Project UID
ONEHOUSE_REGION	Project region
ONEHOUSE_USER_UID	User UID
ONEHOUSE_LINK_UID	Link UID (request ID)
ONEHOUSE_PROFILE	Profile name (equivalent to --profile)
ONEHOUSE_CREDENTIALS_FILE	Path to the credentials file (default: ~/.onehouse/credentials)