lhc models
Manage Lakehousecat custom models. Custom models combine a provider base model with your datasources.
Commands
models list
lhc models list [--type <type>] [--limit N] [--offset N]
| Flag | Default | Description |
|---|---|---|
--type | — | Filter by model type: chat, embedding, text-to-speech, speech-to-text |
--limit | 50 | Maximum number of models |
--offset | 0 | Pagination offset |
models get <id>
lhc models get <model-id>
models search [query]
lhc models search retail
lhc models search retail --limit 50
lhc models search gpt --provider openai
lhc models search --tag RED # every red model, across all pages
Searches models by name, ID, base model ID, or provider type.
| Flag | Description |
|---|---|
--type | Filter by model type, same as on list |
--provider | Filter by provider type, e.g. openai |
--tag | Restrict to models tagged with this color (repeatable, OR-combined; valid colors: RED, YELLOW, GREEN, BLUE, PURPLE). Tags are per user and assigned in the UI — the CLI only filters by them |
The query is optional when --tag is given, but at least one of the two is required.
models create
Creates either a Provider Model (wraps an external LLM provider) or a Custom Model (combines a Provider Model with datasources). Exactly one of --provider-type or --base-model-id must be provided.
Provider Model — wraps an LLM provider endpoint:
lhc models create \
--id <model-id> \
--name <display-name> \
--provider-type Azure \
--provider-model-type Chat
Custom Model — built on top of a Provider Model, optionally with datasources:
lhc models create \
--id <model-id> \
--name <display-name> \
--base-model-id <provider-model-id> \
[--type chat] \
[--datasource-id 1223] \
[--datasource-id 1224]
# With LLM inference parameters
lhc models create \
--id <model-id> \
--name <display-name> \
--base-model-id <provider-model-id> \
--temperature 0.3 \
--system-prompt "Answer concisely."
| Flag | Required | Default | Description |
|---|---|---|---|
--id | yes | — | Unique identifier (letters, digits, underscores, hyphens) |
--name | yes | — | Display name shown in the UI |
--provider-type | one of* | — | Provider type for a Provider Model, e.g. Azure, OpenAI |
--provider-model-type | no | — | Provider model type, e.g. Chat, Embedding, Audio |
--base-model-id | one of* | — | ID of the Provider Model (for a Custom Model) |
--type | no | chat | Model type: chat, embedding, text-to-speech, speech-to-text |
--datasource-id | no | — | Datasource ID to link (repeatable, Custom Model only) |
* Exactly one of --provider-type or --base-model-id is required.
Use lhc models list to find available --base-model-id values. Only Admins can create Provider Models.
See "LLM inference parameters" below for the full list of --temperature/--system-prompt/etc. flags, also available on models create.
models update <id>
Update a custom model's name, state, or configuration:
# Rename
lhc models update <model-id> --name "New Name"
# Replace linked datasources (replaces the full list)
lhc models update <model-id> --datasource-id 1223 --datasource-id 456
# Enable Agent Mode (routes chat to LHC Agent / OpenClaw)
lhc models update <model-id> --agent-enabled=true
# Disable and lock a model
lhc models update <model-id> --is-enabled=false --is-locked=true
# Configure prompt suggestion visibility
lhc models update <model-id> --show-global-suggestions=true --show-model-suggestions=false
| Flag | Description |
|---|---|
--name | New display name |
--datasource-id | Set linked datasource IDs (repeatable — replaces the existing list) |
--agent-enabled | Route chat requests to the LHC Agent service (OpenClaw) instead of the LLM directly |
--is-enabled | Enable (true) or disable (false) the model — disabled models are unavailable for use |
--is-locked | Lock (true) or unlock (false) the model — locked models cannot be edited or deleted |
--is-visible | Control model visibility |
--show-global-suggestions | Display globally configured prompt suggestions for this model |
--show-model-suggestions | Display suggestions defined specifically for this model |
--show-datasource-suggestions | Display prompt suggestions from connected datasources |
At least one flag must be provided. Flags accept =true or =false syntax (e.g. --is-locked=false).
LLM inference parameters (create / update)
Available on both models create and models update — sets Model.params, the per-model
override for temperature, system prompt, and other LLM sampling settings:
lhc models update <model-id> --temperature 0.3 --system-prompt "Answer concisely."
lhc models update <model-id> --max-tokens 2048 --top-p 0.9 --stop "###,END"
lhc models update <model-id> --params-json '{"mirostat":1,"num_ctx":4096}'
| Flag | Constraint | Description |
|---|---|---|
--system-prompt | — | System prompt override for this model |
--temperature | >= 0 | Sampling temperature |
--top-p | 0–1 | Nucleus sampling threshold |
--top-k | >= 0 | Top-k sampling cutoff |
--max-tokens | >= 1 | Maximum output tokens |
--stop | — | Comma-separated stop sequences, e.g. "###,END" |
--frequency-penalty | -2–2 | OpenAI/Azure frequency penalty |
--presence-penalty | -2–2 | OpenAI/Azure presence penalty |
--seed | — | OpenAI/Azure deterministic sampling seed |
--params-json / --params-file | — | Full inference-params block (JSON string or file) — needed for Ollama/Google/AWS niche fields with no dedicated flag (e.g. mirostat, num_ctx) |
Validation ranges are checked client-side before the request is sent, so an out-of-range value fails immediately with a clear message rather than a round-trip 422.
On models update, a single flag like --top-p 0.85 only changes that field — the CLI reads the
model's current params first and merges the new value in, so a previously-set --system-prompt or
--temperature is not lost. This matters because the backend endpoint itself does not merge:
sending a partial params object directly would silently overwrite the rest.
models filters
Manage per-datasource view filters on a Custom Model — a second filter layer, independent of
datasource filters: that one controls what a
datasource loads into ClickHouse at all, this one controls what a specific model then exposes of
it. "Schema" here means view type (entity / metrics / joined_metrics), "table" means the
name of a semantic view, not the underlying database schema/table.
# Show every datasource's filter on this model
lhc models filters get <model-id> --output json
# Show one datasource's filter
lhc models filters get <model-id> --datasource-id 765 --output json
# Set a filter (merges into the existing one for this datasource by default)
lhc models filters set <model-id> --datasource-id 765 --include-tables entity_customer,entity_order
lhc models filters set <model-id> --datasource-id 765 --exclude-tables entity_internal_notes
lhc models filters set <model-id> --datasource-id 765 --filters-file ./views.json --replace
# Clear filters
lhc models filters clear <model-id> --datasource-id 765 --confirm
lhc models filters clear <model-id> --confirm # every datasource on this model
Flag (on set) | Description |
|---|---|
--datasource-id | Required. The linked datasource whose view filter to set |
--include-tables / --exclude-tables | Comma-separated view names, * wildcards supported |
--include-schemas / --exclude-schemas | View-type filter (entity, metrics, joined_metrics) |
--filters-json / --filters-file | Full filter block (JSON string or file) — needed for column- or row-level filters |
--replace | Discard the existing filter for this datasource instead of merging into it |
semantic views <datasource-id> shows the view names available to filter on. Star views (the
model's derived cross-datasource views) cannot be filtered directly — filter their entity/metrics
inputs instead. After changing filters on a model that was already built, run
semantic update model <model-id> --wait so the change takes effect.
models delete <id>
lhc models delete <model-id>
models share <id>
Share a model with a user or group. Exactly one of --user or --group is required:
lhc models share my-gpt4o --user 3e7c3d4f-16ff-4914-8250-bbe693ab7224
lhc models share my-gpt4o --group 1 --permission write
| Flag | Default | Description |
|---|---|---|
--user | — | Target user ID (UUID) |
--group | — | Target group ID (integer) |
--permission | read | Permission level: read, write, owner |
Only Admins can share Provider Models; Builders can share Custom Models they built with Users.
models unshare <id>
Remove a share from a model:
lhc models unshare my-gpt4o --user 3e7c3d4f-16ff-4914-8250-bbe693ab7224
lhc models unshare my-gpt4o --group 1
If the user or group has no share on the model, the command fails with 404 and a non-zero exit code instead of reporting success.
models set-default <id>
Set a model as the default for its type. This controls which model is pre-selected in new sessions:
lhc models set-default <model-id> --type chat
| Flag | Required | Description |
|---|---|---|
--type | yes | Model type: chat, embedding, text-to-speech, speech-to-text |
models export <id>
Export a custom model definition to a portable .lhc.json file. Embedded datasource references are included:
# Print to stdout
lhc models export <model-id>
# Write to file
lhc models export <model-id> -f model.lhc.json
| Flag | Description |
|---|---|
-f, --output-file | Write output to this file (default: stdout) |
models import <file>
Import a model from a .lhc.json export file:
lhc models import model.lhc.json [--name <override-name>]
| Flag | Description |
|---|---|
--name | Override the model name from the export file |
If a model with the same name or ID already exists, the import is aborted with an HTTP 409 error and instructions for resolution.
Exports contain no credentials. As an admin, embedded datasources are re-created without them; as a builder,
database datasources (PostgreSQL, MySQL, MariaDB, …) cannot be re-created and the model arrives without them.
In that case the model is still created, each entry of the response's import_warnings is printed to stderr
as warning: …, and the command exits with status 1. The warnings are not stored — models get shows
null afterwards. Complete the import with datasources import --connection-string … followed by
models update <id> --datasource-id ….
models count / models statistics
count returns the total number of models. statistics returns aggregated model statistics —
Admins see global figures, everyone else sees their own:
lhc models count
lhc models statistics
Cloning
models clone <id>
Clone a Custom Model's metadata only — no descriptions, hierarchies, or warehouse data. Provider Models cannot be cloned:
lhc models clone my-custom-model --new-name "Copy of my-custom-model"
| Flag | Required | Description |
|---|---|---|
--new-name | yes | Name for the cloned model |
models deep-clone <id>
Clone a Custom Model including its descriptions, hierarchies, suggestions, and — unless
--no-data is given — its extracted data as well:
lhc models deep-clone my-custom-model --new-name "Full copy"
lhc models deep-clone my-custom-model --new-name "Metadata only" --no-data
| Flag | Required | Description |
|---|---|---|
--new-name | yes | Name for the cloned model |
--no-data | no | Skip the data copy — metadata, descriptions, hierarchies, and suggestions only |
Copying the data can take a while. The command returns as soon as the clone has been started, so
poll models clone-status on the new model rather than treating the response as completion.
models clone-status <id>
Status of a clone — use this to poll a running deep-clone:
lhc models clone-status my-custom-model-clone
models batch-deep-clone
Deep-clone several Custom Models in one request. The file holds a JSON array of objects with
model_id, new_name, and optionally clone_clickhouse (default true):
lhc models batch-deep-clone --file clones.json
[
{ "model_id": "a", "new_name": "a copy" },
{ "model_id": "b", "new_name": "b copy", "clone_clickhouse": false }
]
| Flag | Required | Description |
|---|---|---|
--file | yes | Path to the JSON file with the clone requests |
The response lists results and errors per entry plus successful/failed. If any entry fails, the
command exits non-zero (HTTP 207) and prints each failure to stderr; entries that succeeded stay created,
so check lhc models search "<new_name>" before retrying. An empty array is rejected with HTTP 400.
Operations and backend defaults
models operations <id>
Enable or disable a Custom Model's semantic-model operations (Admin/Builder only). Each of create, update, and delete can be toggled independently; operations you do not name are left unchanged, and at least one flag is required:
lhc models operations my-custom-model --disable-delete
lhc models operations my-custom-model --disable-create --disable-update
| Flag | Description |
|---|---|
--enable-create / --disable-create | Allow or block creating semantic models |
--enable-update / --disable-update | Allow or block updating semantic models |
--enable-delete / --disable-delete | Allow or block deleting semantic models |
The enable and disable flag of the same operation are mutually exclusive.
models get-backend-default / models set-backend-default <id>
The backend default is a separate mechanism from the front-end default that set-default
controls — setting one does not affect the other. set-backend-default is Admin-only:
lhc models get-backend-default --type chat
lhc models set-backend-default my-gpt4o --type chat
| Flag | Default | Description |
|---|---|---|
--type | chat | Model type: chat, embedding, text-to-speech, speech-to-text |
models sharing <id>
Show the sharing summary for one model — who it is shared with and at which permission level:
lhc models sharing my-gpt4o
models shared-by-me / models shared-with-me
List models you have shared with others, or models others have shared with you:
lhc models shared-by-me
lhc models shared-with-me