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

The skill requires onehouse-cli 0.3.0 or later. Run oh --version to check your version, and pip install --upgrade onehouse-cli to upgrade.

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

• How to install the CLI and set up credentials with oh-configure, including multi-org profiles
• All oh command groups, their flags, and the SQL statement that each command runs
• Rules for safe operation: previews with --show-sql, deletes that run without confirmation, and cascades
• Async operations and recovery from timeouts
• Raw SQL with oh sql exec for operations that have no CLI command
• Troubleshooting, with links to the related SQL reference pages

To read the skill without installing it, run oh skill.

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)