onehouse-cli 0.1.4__tar.gz → 0.3.0__tar.gz

onehouse_cli-0.3.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: onehouse-cli
+Version: 0.3.0
+Summary: A command-line tool for the full Onehouse API
+Author-email: Sagar Lakshmipathy <18vidhyasagar@gmail.com>
+License: Proprietary
+Keywords: onehouse,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: onehouse-python-sdk[resources]
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+
+# 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
+
+```bash
+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:
+
+```bash
+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:**
+```bash
+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:
+```bash
+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
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--profile` / `-p` | `_default` key in credentials file | Credentials profile to use |
+| `--timeout` / `-t` | `10` | Minutes to wait for async operations |
+| `--output` / `-o` | `table` | Output format: `table` or `json` |
+
+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
+```bash
+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
+```bash
+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
+```bash
+oh database show   --lake LAKE_NAME
+oh database create DB_NAME --lake LAKE_NAME
+oh database delete DB_NAME --lake LAKE_NAME [--cascade]
+```
+
+### Tables
+```bash
+oh table show --lake LAKE_NAME --database DB_NAME
+```
+
+### Table Services
+```bash
+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
+```bash
+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
+```bash
+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
+```bash
+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
+```bash
+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
+```bash
+oh validation show
+oh validation describe VAL_NAME
+oh validation create   VAL_NAME --type SCHEMA
+oh validation delete   VAL_NAME
+```
+Types: `SCHEMA`, `TIMESTAMP`
+
+### Jobs
+```bash
+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
+```bash
+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
+```bash
+oh api-token create TOKEN_NAME --service-principal SP_NAME
+oh api-token delete TOKEN_NAME --service-principal SP_NAME
+```
+
+### Raw SQL
+```bash
+# 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):
+```bash
+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:
+```bash
+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
+
+```bash
+# 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 '.'
+```

onehouse_cli-0.3.0/README.md

@@ -0,0 +1,274 @@
+# 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
+
+```bash
+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:
+
+```bash
+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:**
+```bash
+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:
+```bash
+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
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--profile` / `-p` | `_default` key in credentials file | Credentials profile to use |
+| `--timeout` / `-t` | `10` | Minutes to wait for async operations |
+| `--output` / `-o` | `table` | Output format: `table` or `json` |
+
+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
+```bash
+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
+```bash
+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
+```bash
+oh database show   --lake LAKE_NAME
+oh database create DB_NAME --lake LAKE_NAME
+oh database delete DB_NAME --lake LAKE_NAME [--cascade]
+```
+
+### Tables
+```bash
+oh table show --lake LAKE_NAME --database DB_NAME
+```
+
+### Table Services
+```bash
+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
+```bash
+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
+```bash
+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
+```bash
+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
+```bash
+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
+```bash
+oh validation show
+oh validation describe VAL_NAME
+oh validation create   VAL_NAME --type SCHEMA
+oh validation delete   VAL_NAME
+```
+Types: `SCHEMA`, `TIMESTAMP`
+
+### Jobs
+```bash
+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
+```bash
+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
+```bash
+oh api-token create TOKEN_NAME --service-principal SP_NAME
+oh api-token delete TOKEN_NAME --service-principal SP_NAME
+```
+
+### Raw SQL
+```bash
+# 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):
+```bash
+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:
+```bash
+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
+
+```bash
+# 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 '.'
+```

onehouse_cli-0.3.0/onehouse_cli/__init__.py

@@ -0,0 +1,32 @@
+"""
+Onehouse CLI - A command-line tool for executing SQL commands against the Onehouse API.
+"""
+
+try:
+    # For Python 3.8+
+    from importlib.metadata import version
+except ImportError:
+    # For Python 3.7
+    from importlib_metadata import version
+
+try:
+    __version__ = version("onehouse-cli")
+except Exception:
+    # Fallback version if package is not installed
+    __version__ = "0.0.0.dev"
+
+__all__ = ["cli_main", "configure_main"]
+
+
+# Imported lazily (PEP 562) so that pulling in a leaf module does not drag in
+# the whole command tree — and with it the SDK dependency. This keeps
+# `oh-skill` readable on an install where onehouse-python-sdk is missing,
+# which is precisely when someone needs the usage guide.
+def __getattr__(name):
+    if name == "cli_main":
+        from .cli import main
+        return main
+    if name == "configure_main":
+        from .configure import main
+        return main
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

onehouse_cli-0.3.0/onehouse_cli/cli.py

@@ -0,0 +1,102 @@
+"""
+Onehouse CLI — top-level Click entry point.
+
+Global options (--profile, --timeout, --output) are propagated to every
+subcommand via the Click context object (ctx.obj).
+"""
+
+import click
+
+from . import __version__
+from .commands import (
+    cluster,
+    lake,
+    database,
+    table,
+    catalog,
+    source,
+    flow,
+    transformation,
+    validation,
+    job,
+    service_principal,
+    api_token,
+    install,
+    skill as skill_cmd,
+    sql as sql_cmd,
+)
+
+
+_EPILOG = """\
+Agents and new users: run `oh skill` for a complete usage guide covering
+credential setup, the SQL each command emits, and destructive-operation safety.
+
+Note: deletes execute immediately with no confirmation prompt. Use --show-sql
+on any command to preview the statement without running it.
+"""
+
+
+class CliContext:
+    def __init__(self, profile: str | None, timeout: int, output: str):
+        self.profile = profile
+        self.timeout = timeout
+        self.output = output
+
+
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    epilog=_EPILOG,
+)
+@click.version_option(__version__, "-v", "--version")
+@click.option(
+    "--profile", "-p",
+    default=None,
+    envvar="ONEHOUSE_PROFILE",
+    help="Credentials profile to use (default: profile named in _default key).",
+)
+@click.option(
+    "--timeout", "-t",
+    default=10,
+    show_default=True,
+    type=int,
+    help="Timeout in minutes for async operations.",
+)
+@click.option(
+    "--output", "-o",
+    default="table",
+    show_default=True,
+    type=click.Choice(["table", "json"], case_sensitive=False),
+    help="Output format for results.",
+)
+@click.pass_context
+def cli(ctx: click.Context, profile: str | None, timeout: int, output: str) -> None:
+    """Onehouse CLI — manage your Onehouse project from the command line."""
+    ctx.ensure_object(dict)
+    ctx.obj = CliContext(profile=profile, timeout=timeout, output=output)
+
+
+cli.add_command(cluster.cluster)
+cli.add_command(lake.lake)
+cli.add_command(database.database)
+cli.add_command(table.table)
+cli.add_command(catalog.catalog)
+cli.add_command(source.source)
+cli.add_command(flow.flow)
+cli.add_command(transformation.transformation)
+cli.add_command(validation.validation)
+cli.add_command(job.job)
+cli.add_command(service_principal.service_principal, name="service-principal")
+cli.add_command(api_token.api_token, name="api-token")
+cli.add_command(sql_cmd.sql)
+cli.add_command(skill_cmd.skill)
+cli.add_command(install.install)
+
+
+def main() -> None:
+    # Standalone mode turns Click errors into a one-line `Error: ...` message
+    # and the conventional exit code (1 = failure, 2 = usage error).
+    cli()
+
+
+if __name__ == "__main__":
+    main()