lhc instance

Show information about the connected Lakehousecat instance, and rotate its encryption key.

Commands

instance info

Fetches instance metadata including the license state, expiry, and seat count.

lhc instance info
lhc instance info --output json
lhc instance info --output yaml

Example output (table):

INSTANCE_ID                            EXPIRES_AT   SUBSCRIPTION_STATE   USER_SEAT_COUNT
eb0e938e-ff73-4e53-b20e-e74d1e021541   2027-01-01   active               10

Example output (JSON):

{
  "instance_id": "eb0e938e-ff73-4e53-b20e-e74d1e021541",
  "expires_at": "2027-01-01",
  "subscription_state": "active",
  "user_seat_count": 10
}

Use instance info as a connectivity check after configuring a new profile.

---

instance rotate-encryption-key

Rotate the instance's encryption key (ENCRYPT_KEY). Requires Admin permissions.

Runs as a background job on the backend — this command returns immediately with a run ID; poll its progress with instance rotate-encryption-key-status. Defaults to a dry run, which only counts rows pending rotation and writes nothing:

lhc instance rotate-encryption-key
lhc instance rotate-encryption-key --apply
lhc instance rotate-encryption-key --apply --table user --table model

Flag	Default	Description
--apply	false	Actually rewrite rows. Without it, the command only counts what would change
--table	—	Limit the run to this table (repeatable). Omit to rotate every table that holds encrypted content

Example output:

{ "run_id": 3 }

Before running this: the old key must already be reachable by the backend as a read fallback, alongside the new key that is already active. See Encryption Key Rotation for the full, ordered procedure — running this command out of order can make encrypted data unreadable.

---

instance rotate-encryption-key-status <run-id>

Check the progress of a rotation run started with instance rotate-encryption-key:

lhc instance rotate-encryption-key-status 3

Example output (JSON):

{
  "run_id": 3,
  "status": "completed",
  "mode": "apply",
  "primary_key_fingerprint": "60e202ae",
  "tables": {
    "chart": { "scanned": 42, "pending": 42, "rewritten": 42 },
    "datasource": { "scanned": 5, "pending": 0, "rewritten": 0 }
  },
  "error": null,
  "created_at": 1787931801,
  "updated_at": 1787931825
}

status is one of pending, running, completed, or failed. Each table's tally reports scanned (rows read), pending (rows not yet encrypted with the current key), and rewritten (rows actually rewritten — always 0 for a dry run). If status is failed, error names the row and reason — most commonly a row encrypted with a key that isn't available as a read fallback. The run stops immediately rather than skip the row silently; re-running is safe once the missing key is back in place, since already-rotated rows are skipped automatically.