Onehouse CLI (oh)

A command-line tool for managing your Onehouse project — clusters, lakes, databases, tables, flows, jobs, catalogs, sources, transformations, validations, service principals, and API tokens.

Installation

pip install onehouse-cli

The SDK dependency (onehouse-python-sdk[resources]) is installed automatically.

AI agent integration

The package bundles a skill that teaches AI coding agents how to use oh. Install it for your agent:

oh install agent-skill --claude    # ~/.claude/skills/onehouse-cli
oh install agent-skill --cursor    # ~/.cursor/skills/onehouse-cli
oh install agent-skill --codex     # ~/.agents/skills/onehouse-cli
oh install agent-skill --all       # all of the above
oh install agent-skill --all --dry-run

Re-run the command after pip install --upgrade onehouse-cli to refresh the skill. To read the skill without installing it, run oh skill.

Setup

Configure credentials:

oh-configure

This prompts for your API credentials and saves them to ~/.onehouse/credentials. You can create multiple named profiles and set a default.

Fields collected:

• Profile name
• Account UID
• Project UID
• API Key / API Secret
• Project Region
• User ID
• Request ID (link UID)
• API Endpoint (default: https://api.onehouse.ai/v1)

Credentials are stored in: ~/.onehouse/credentials

Alternatively, set environment variables:

export ONEHOUSE_API_KEY=...
export ONEHOUSE_API_SECRET=...
export ONEHOUSE_ACCOUNT_UID=...
export ONEHOUSE_PROJECT_UID=...
export ONEHOUSE_REGION=...
export ONEHOUSE_USER_UID=...
export ONEHOUSE_LINK_UID=...
export ONEHOUSE_PROFILE=myprofile   # select a profile from the credentials file

Global Options

oh [--profile NAME] [--timeout MINS] [--output table|json] COMMAND

Every command also accepts --show-sql to print the generated SQL statement without executing it.

onehouse-cli and onehouse-cli-configure are kept as aliases for backward compatibility.

Commands

Clusters

oh cluster show
oh cluster describe CLUSTER_NAME
oh cluster create CLUSTER_NAME --type SQL --max-ocu 10 --min-ocu 2
oh cluster alter  CLUSTER_NAME --state STOP
oh cluster alter  CLUSTER_NAME --max-ocu 20
oh cluster alter  CLUSTER_NAME --new-name NEW_NAME
oh cluster delete CLUSTER_NAME

Cluster types: Managed, SQL, Spark, Open_Engines, Notebook, LakeBase

Lakes

oh lake show
oh lake create LAKE_NAME --type MANAGED --bucket-path s3://my-bucket/ --default-services-cluster mycluster
oh lake alter  LAKE_NAME --default-services-cluster newcluster
oh lake delete LAKE_NAME [--cascade]

Databases

oh database show   --lake LAKE_NAME
oh database create DB_NAME --lake LAKE_NAME
oh database delete DB_NAME --lake LAKE_NAME [--cascade]

Tables

oh table show --lake LAKE_NAME --database DB_NAME

Table Services

oh table service create    --lake L --database D --table T --service COMPACT --trigger-mode ON_DEMAND
oh table service alter     --lake L --database D --table T --service COMPACT --trigger-mode AUTOMATIC
oh table service describe  --lake L --database D --table T --service COMPACT
oh table service show      --lake L --database D --table T
oh table service show-runs --lake L --database D --table T --service COMPACT
oh table service run       --lake L --database D --table T --service COMPACT
oh table service pause     --lake L --database D --table T --service COMPACT
oh table service resume    --lake L --database D --table T --service COMPACT
oh table service cancel    --lake L --database D --table T --service COMPACT
oh table service alter-cluster --lake L --database D --table T --services-cluster newcluster

Services: CLUSTER, COMPACT, CLEAN, METASYNC
Run-only services (for run): CLUSTER, COMPACT, CLEAN, METASYNC, AUTOSAVEPOINT, RESTORE

Catalogs

oh catalog show
oh catalog describe CATALOG_NAME
oh catalog create   CATALOG_NAME --type GLUE --credential-type CREDENTIAL_TYPE_ONEHOUSE
oh catalog delete   CATALOG_NAME

Types: GLUE, HIVE, BIGQUERY, DATAHUB, ONETABLE, DATAPROC, UNITY, SNOWFLAKE, ONELAKE

Sources

oh source show
oh source describe SOURCE_NAME
oh source create   SOURCE_NAME --type S3 --credential-type CREDENTIAL_TYPE_ONEHOUSE [--if-not-exists]
oh source delete   SOURCE_NAME

Types: APACHE_KAFKA, MSK_KAFKA, CONFLUENT_KAFKA, S3, GCS, ONEHOUSE_TABLE, POSTGRES, MY_SQL

Flows

oh flow show
oh flow describe FLOW_NAME
oh flow create   FLOW_NAME \
    --source mysource --lake mylake --database mydb --table-name mytable \
    --write-mode IMMUTABLE --cluster mycluster \
    [--performance-profile BALANCED] \
    [--record-key-fields id] \
    [--partition-key-fields date:DATE_STRING] \
    [--precombine-key-field ts] \
    [--min-sync-frequency-mins 5] \
    [--quarantine-enabled] \
    [--catalogs cat1] [--transformations tx1] [--validations val1]
oh flow alter  FLOW_NAME --state PAUSE          # or RESUME, CLEAN_AND_RESTART
oh flow alter  FLOW_NAME --cluster newcluster   # exactly one option at a time
oh flow delete FLOW_NAME

Partition key field format: FIELD:TYPE:INPUT_FORMAT:OUTPUT_FORMAT
Write modes: IMMUTABLE, MUTABLE
Performance profiles: BALANCED, FASTEST_READ, FASTEST_WRITE

Transformations

oh transformation show
oh transformation describe TX_NAME
oh transformation create   TX_NAME --type ROW_FILTERING [--options FILTER_SQL="col > 0"]
oh transformation delete   TX_NAME

Types: CONVERT_CDC, ROW_FILTERING, DERIVED_DATE, ADD_CURRENT_TIMESTAMP, USER_PROVIDED, DATA_MASKING, L_PARSE_JSON, FLATTEN_STRUCT, EXPLODE_ARRAY, VECTOR_EMBEDDING

Validations

oh validation show
oh validation describe VAL_NAME
oh validation create   VAL_NAME --type SCHEMA
oh validation delete   VAL_NAME

Types: SCHEMA, TIMESTAMP

Jobs

oh job show
oh job describe      JOB_NAME
oh job create        JOB_NAME --type JAR --cluster mycluster --parameters arg1 --parameters arg2
oh job create-and-run JOB_NAME --type PYTHON --cluster mycluster --parameters script.py
oh job alter         JOB_NAME --cluster newcluster     # or --parameters (not both)
oh job run           JOB_NAME
oh job cancel-run    JOB_RUN_UUID --job-name JOB_NAME
oh job describe-run  JOB_RUN_UUID --job-name JOB_NAME
oh job show-runs     JOB_NAME
oh job upload-jar    JAR_NAME --options FILE_PATH=/path/to/file.jar
oh job replace-jar   JAR_NAME --options FILE_PATH=/path/to/file.jar

Job types: JAR, PYTHON

Service Principals

oh service-principal show
oh service-principal create SP_NAME
oh service-principal alter  SP_NAME --new-name NEW_NAME
oh service-principal delete SP_NAME

API Tokens

oh api-token create TOKEN_NAME --service-principal SP_NAME
oh api-token delete TOKEN_NAME --service-principal SP_NAME

Raw SQL

# Execute any SQL statement
oh sql exec --command "SHOW CLUSTERS"

# Fire-and-forget (returns request ID immediately, no polling)
oh sql exec --command "SHOW CLUSTERS" --async-mode

# Check status of a previous request
oh sql status REQUEST_ID

WITH options

Commands that accept extra configuration take --options KEY=VALUE (repeatable):

oh catalog create mycat --type HIVE \
    --credential-type CREDENTIAL_TYPE_ONEHOUSE \
    --options METASTORE_URI=thrift://host:9083 \
    --options DATABASE=default

Show SQL

Any command can print its generated SQL without making a network call:

oh cluster create mycluster --type SQL --show-sql
# CREATE CLUSTER `mycluster`
#   TYPE = 'SQL'

oh flow create myflow --source src --lake l --database d \
    --table-name t --write-mode IMMUTABLE --cluster c --show-sql

Examples

# Create a managed lake and database
oh lake create prod-lake --type MANAGED \
    --bucket-path s3://my-data-lake/ \
    --default-services-cluster services-cluster
oh database create analytics --lake prod-lake

# Create a Kafka flow
oh source create kafka-src --type APACHE_KAFKA \
    --credential-type CREDENTIAL_TYPE_ONEHOUSE \
    --options BOOTSTRAP_SERVERS=kafka:9092
oh flow create orders-flow \
    --source kafka-src --lake prod-lake \
    --database analytics --table-name orders \
    --write-mode MUTABLE --cluster ingest-cluster \
    --record-key-fields order_id

# Monitor a table's compaction service
oh table service show --lake prod-lake --database analytics --table orders
oh table service run  --lake prod-lake --database analytics --table orders --service COMPACT

# JSON output for scripting
oh --output json cluster show | jq '.'