# LimiLake CLI 0.1.72 documentation

Docs identity: limilake-cli/0.1.72

Source commit: 55defbcce3cfa20172238eaded03fa9a594fba53

## Install this exact release

This context describes CLI `0.1.72` from source `55defbcce3cfa20172238eaded03fa9a594fba53`. It supports Linux and macOS on AMD64 and ARM64; Windows is not supported by this release.

```bash
curl -fsSL https://get.limilake.com/ | sh -s -- --version 0.1.72
limilake --output json version
```

Immutable manifest: https://packages.limilake.com/cli/v0.1.72/manifest.json

Internal GitHub Release audit (repository access required): https://github.com/liminityab/limilake-v2/releases/tag/cli/v0.1.72

Stock macOS OpenSSH key: https://packages.limilake.com/cli/v0.1.72/release-public-key.pub

Version-matched context: https://packages.limilake.com/cli/v0.1.72/llms.txt

Expected identity: version `0.1.72`, source `55defbcce3cfa20172238eaded03fa9a594fba53`, and the machine's actual `os`, `arch`, and Go toolchain. Executable updates are explicit; bare/root help may make one anonymous cached stable-channel check, while subcommands never check automatically. Explicit `version --check` verifies stable metadata; `upgrade` replaces the executable only after signed verification. The CLI sends no usage telemetry.

After authentication, preserve ordinary Git ownership of repository operations:

```bash
limilake workspace list
limilake workspace clone <workspace>
cd <workspace>
git fetch
git switch -c <branch>
git push origin HEAD:drafts/workspace # save work in progress
git push origin HEAD:main # publish this revision
limilake workspace doctor
```

---

<!-- SKILL.md -->

---
title: LimiLake CLI primer
slug: SKILL
summary: Must-know conventions for operating LimiLake from the terminal, and when to read more.
---

# LimiLake CLI primer

You are operating a LimiLake workspace through the `limilake` CLI. Prefer it over guessing from training data — the platform's nouns and verbs are specific. When a detail is not covered here, run `limilake docs <topic>` (offline) or `limilake <domain> explain` for live state.

## Mental model

- **Workspace** -> **lakehouse** -> **schema** -> **table** / **file**.
- Code is **functions** (`.py`) and **apps** (`.app.tsx`), authored as files in the workspace git repo. Ordinary files such as `README.md` are valid Workspace source too.
- A Function lives at `functions/<slug>/function.py`. Scaffold it with `limilake add function <slug>` so its declaration matches the Workspace Contract: Contract v2 generates `function(id=, name=, description=, access=, run_as=)` with durable identity, while the Contract v1 compatibility scaffold omits the v2-only `id`. For an MCP-exposed Function, `description=` becomes the first paragraph of its projected tool description.
- Data containers (lakehouses) are **server-side platform objects** — discover and provision them via the API, never via a repo file.

## Act inline (don't ask) for

- Discovery: `limilake workspace list`, `limilake lakehouse list`, `limilake table list --lakehouse <ref>`, `limilake lakehouse explain <name>`.
- Read-only queries: `limilake query "SELECT ..." --lakehouse <ref>` and `limilake table read <schema.table> --lakehouse <ref>`.
- Inspecting executions: `limilake execution list`, `limilake execution view <id>`, `limilake execution logs <id>`, `limilake function logs <path>`, and `limilake function watch <path> <run-id>` for a durable Function Run (the Run ID is not the linked Execution ID).

## Confirm first for

- Mutations: creating/deleting workspaces or lakehouses, changing live Workspace source, granting credentials, revoking tokens.
- Anything that changes live Workspace behavior: pushing an accepted revision to `main` makes valid Function routes and schedules current after indexing, queues its exact Build, and automatically activates successful App artifacts. `limilake publication rollback <deployment-manifest-id>` moves the App publication pointer back to an older retained Deployment Manifest. Rollback changes what an App serves right now; inspection (`limilake publication show`) works from any session.

## Conventions

- `--output table|json|yaml` selects record presentation. Completion scripts,
  raw downloads, Git credential responses and live child/stream protocols keep
  their own stdout format. For `file download`/`file get`, use `--output-file PATH`
  and put `--result-schema v1 -o json` before `file` for versioned metadata.
  Retained `-o/--output PATH` after the verb still selects a destination during
  the deprecation window. `LIMILAKE_OUTPUT` always selects the format.
  Use JSON only when the command documents a structured result.
- Authentication is per-profile; `--profile <name>` overrides the active account. Inside a sandbox, credentials are injected automatically — no login needed.
- Queries are read-only and bounded; the real access boundary is enforced server-side, so a query only ever sees data your grants allow.
- In an ordinary signed standalone CLI install, inspect the exact managed Build toolchain with `limilake toolchain doctor`; use `limilake toolchain repair` only when its report names repair as the next action.
- `limilake build` uses the same Build Engine as production. Signed standalone installs use the exact managed cache; the hosted LimiLake Agent image instead uses its image-pinned engine and base-image tools, so `toolchain doctor` and `repair` do not govern that override. Use `--offline` only when the active toolchain and required pnpm-store dependencies are already present; project manifests and frozen lockfiles remain authoritative.

- There is no separate Function deployment. The accepted `main` revision is the source publication: valid Function routes and schedules become current after it is indexed, while successfully built App artifacts activate through the Publication pointer.
- Human Git credentials may push either the editor Draft or protected `main`: use `git push origin HEAD:drafts/workspace` for work in progress, or `git push origin HEAD:main` to publish. Every accepted `main` push queues an exact-SHA production Build. A Contract-v2 revision may contain Apps, Functions, both, or neither (for example only `README.md`) and still produces a valid no-op manifest for absent surfaces. Build and App delivery attempts remain inspectable with `limilake publication show`; return an App to a retained Deployment Manifest with `limilake publication rollback <deployment-manifest-id>`.
- Commit the intended files before pushing. Those two refs are the only human push targets: keep feature branches local and use an explicit `HEAD:<target>` push. A `[code=git_ref_not_allowed]` rejection names an unsupported target; `[code=git_multi_ref_unsupported]` means `main` must be pushed separately. Run `limilake explain git_ref_not_allowed` or `limilake explain git_multi_ref_unsupported` for the matching recovery instructions. Source-validation errors on `main` require fixing the named file and committing again. Action/sync handlers take no parameters or one required `dict[str, T]` input parameter without a default.

## When to read more

- Git or CLI rejection recovery -> `limilake explain <code>` for an offline explanation, or `limilake docs push-rejections` for the complete code index; neither needs a profile or login.
- How functions expose actions/HTTP/sync/schedules -> `limilake docs functions`.
- Running an agent from code (`agent.run()`), resuming it by session, and scheduling it -> `limilake docs agents`.
- Lakehouses, schemas, and SQL -> `limilake docs querying-data`.
- Reaching external providers without raw secrets -> `limilake docs connections`.
- Reporting platform friction safely -> `limilake docs reporting-problems`.
- First-time setup -> `limilake docs getting-started`.

---

<!-- agents.md -->

---
title: Agents
slug: agents
summary: Run an agent from code with agent.run(), resume it by session, and schedule it as a normal function.
---

# Agents

An **agent** is an autonomous LLM run that LimiLake executes server-side in a sandbox. The same primitive backs an interactive chat, a code-invoked run, and a scheduled run — there is one kind of thing, reached three ways. From code you invoke one with the `agent` capability, exactly like `lake` and `connections`:

```python
from limilake import agent

result = agent.run("Summarize yesterday's invoices and flag anything materially off")
print(result.output)
```

`agent.run()` is a thin API client, not a local process spawn: it POSTs the prompt to the backend, which authorizes the caller, mints a narrowed token, launches the agent headless, blocks until it finishes, and returns the final assistant message. Because the agent runs server-side, the same call works from a laptop, from CI, and from inside a scheduled sandbox.

## Surface

```python
agent.run(prompt, *, session=None, scope=None, timeout=None) -> AgentResult
agent.start(prompt, *, session=None, scope=None, timeout=None) -> AgentHandle
```

- **`agent.run(prompt, ...)`** blocks until the agent reaches a terminal state and returns an `AgentResult`. This is the default for the "check, then invoke, then act" pattern below.
- **`agent.start(prompt, ...)`** returns an `AgentHandle`; call `handle.result()` to get the `AgentResult`. The v1 server is synchronous, so the run is already complete when the handle is returned — `start` exists so calling code is forward-compatible with the deferred async launch/poll path.

`AgentResult` is a frozen dataclass:

- **`.output`** — the agent's final assistant message text.
- **`.session`** — the durable agent id the run resolved to. Pass it back as `session=` to resume.
- **`.status`** — the terminal run status: `completed`, `failed`, or `timeout`.
- **`.usage`** — an opaque per-run usage dict (model, tokens) in v1; treat it as a pass-through.

A failed invocation raises `AgentInvokeError`, which carries the backend HTTP `status_code` and a machine-readable `code` so you can branch on a permission denial versus a transient failure.

## Sessions and Tier-1 memory

The `session` argument is the continuity handle. It is a **stable name**, resolved per workspace as a create-if-missing idempotency key:

- The first call with a given name creates the durable agent and runs it fresh.
- Later calls with the same name **resume the same agent and append the prompt** — "check again" reasons against everything that came before.

```python
first = agent.run("Investigate this week's churn", session="churn-watch")
again = agent.run("Now compare against last week", session="churn-watch")  # resumes
```

The transcript lives on a persistent volume, so continuity survives the sandbox being torn down between runs. This is **Tier-1 memory**: the session *is* the memory, exactly like a human returning to a chat. There is no separate memory file to manage in v1.

A `session` name is an idempotency key scoped to the workspace and the run-as owner — it is not a global handle, so two functions using the same name do not cross-resume into each other's transcript. Omit `session` for a fresh, ephemeral run with no continuity.

## Visibility and trigger types

Every agent carries a **trigger** (how it was started) and an **`is_private`** (incognito) flag.

- **Trigger** is how the agent was started: `interactive` (a chat), `on_demand` (run-now from a user or the CLI), or `code` (an `agent.run()` from a notebook or function body — including a scheduled function whose body calls `agent.run()`). All trigger types render in the same unified Agents list, filterable by type.
- **`is_private`** (incognito) scopes an agent's *reads* to its creator. Agents are workspace-visible by default; an incognito agent is hidden from other members. Visibility only broadens **reads** — attaching to, driving, or mutating a running agent stays owner-only.

Set incognito at create time in the UI, or toggle it per agent. Existing transcripts predating this feature are all private.

## Scope and what a code-invoked agent can do

A code-invoked `agent.run()` does **not** run with your full rights. The backend mints a **narrowed** token, server-side, that is never trusted to the SDK:

- It starts from a reduced default — read-only lake and workspace access (`workspace:read`, `workspace:lake:read`), the LLM and agent-tooling capabilities, and **egress proxy** for connection-proxied calls — plus the caller's granted connection refs.
- It is intersected with the **authenticated caller's** actual grants, so an `agent.run()` from inside a sandbox can never escalate above what its caller holds.
- It **hard-excludes** `egress:reveal`, `workspace:write`, and `workspace:lake:write` for any non-interactive run. The prompt is attacker-influenceable data, so a prompt-injected agent's worst case is read plus connection-proxied POST.

The optional **`scope`** argument can only *narrow* the **data-plane** scopes further (intersect-only). A scope you pass can drop data authority from the default set; it can never add authority the caller does not already hold. The LLM and agent-tooling capabilities are always retained, so a narrowed run is still a runnable agent.

```python
# Restrict this run's data plane to lake reads only — no egress at all.
# (LLM and agent tooling stay available, so the agent can still run.)
result = agent.run(prompt, scope=["workspace:lake:read"])
```

An agent cannot invoke another agent: a call made from inside an agent sandbox is rejected server-side.

## Notifying via connections

There is no separate notification API. An agent "notifies" by calling an HTTP **Connection** (a Slack webhook, an email provider, PagerDuty) through the egress proxy, with the credential injected server-side — the same path any provider call takes. To let an agent alert a channel, grant it the connection and mention it in the prompt:

```python
agent.run(
    "If today's revenue dropped more than 20% vs the 7-day average, "
    "post a one-line summary to the 'slack-finance' connection.",
)
```

Dropping `egress:reveal` from the narrowed token does **not** break this: posting to a connection uses `egress:proxy` (server-side injection), not reveal. See `limilake docs connections`.

## Scheduling an agent

Scheduling is **not** a new CLI verb. A scheduled agent is just a normal function with a `schedule=` whose body calls `agent.run()`. It rides the existing cron spine — the same leases, concurrency policy, and retry behavior every function gets.

```python
from limilake import function, lake, agent

fn = function(name="invoice-watch", schedule="0 7 * * *")  # daily at 07:00


@fn.action
def run() -> dict[str, object]:
    # Deterministic check FIRST: cheap, no LLM, fully programmable.
    n = lake.query("select count(*) n from bronze.invoices where date = current_date")[0]["n"]
    if n == 0:
        return {"skipped": "no new invoices"}  # never spend an agent

    # Escalate to an agent only when warranted.
    r = agent.run(
        "Investigate today's invoices and report anything materially off. "
        "If something needs attention, post a summary via the 'slack-finance' connection.",
        session="invoice-watch",  # stable name => same durable agent each fire
    )
    return {"checked": n, "summary": r.output}
```

This **deterministic-check-then-invoke** shape is the intended pattern: do the cheap, fully-programmable check in plain code, and only pay for an agent when the check says it is worth it. The agent's session name keeps every fire continuous with the last.

Notes for scheduled agents:

- **Cadence floor.** A schedule that drives an agent must fire at most once every 15 minutes; daily or weekly is the economic sweet spot, since each fire is a sandbox plus a multi-turn LLM loop.
- **Concurrency.** Set the function to forbid overlap (`max_concurrent_runs=1`) so a slow fire is skipped, not stacked.
- **Dedup.** Do your own "did I already handle this?" check in code (for example a high-water-mark in a lake table). There is no dedicated cursor subsystem in v1.

See `limilake docs functions` for the full function/scheduling surface.

## Where it runs

`pi` (the agent runtime) lives only server-side. `agent.run()` carries no local LLM — it authorizes against the backend, which launches the agent headless in a managed sandbox and captures the result. Inside a managed sandbox the token and workspace are injected automatically; from a laptop or CI, set `LIMILAKE_TOKEN` (or `LIMILAKE_TOKEN_FILE`) and `LIMILAKE_WORKSPACE_ID`.

---

<!-- cli-reference.md -->

---
title: CLI command reference
slug: cli-reference
summary: Commands, flags, examples, and pagination from the CLI's own help source.
---

# CLI command reference

<!-- Generated by sdk/cli/cmd/reference. Do not edit. -->

The examples and options below are the same source used by command help. Use names and IDs returned by your own account. Signed release llms.txt includes the reference from that exact source version.

## Common flags

Common options work before, between, and after command words.
Selection is explicit CLI input > environment > saved/local context > command default.
The last repeated singleton wins. A conflicting positional and flag target is refused;
a positional target overrides environment defaults. -- ends option parsing; use
--profile=--literal for a flag-like value.
When used as fallback, LIMILAKE_WORKSPACE and LIMILAKE_WORKSPACE_ID must agree;
an explicit --workspace settles that conflict. Unused defaults are ignored.
Account/local commands keep their existing Workspace applicability. Table discovery
accepts an explicit --workspace filter only; environment/checkout omission stays
aggregate under the legacy Workspace policy. Other commands retain their existing selection behavior.
Injected authenticated Workspace bindings cannot be overridden.
--no-input suppresses prompts/browser opening, allows explicit stdin, and never
implies --yes. Missing prompted input exits 2; legacy setup requirements keep exit 1.
Commands using checkout authentication context (including auth status, lake query,
and ask) report malformed or identity-less bindings and invalid binding profile
names as exit 2; unreadable binding files exit 5. Diagnostics retain the checkout,
failing file path, and original filesystem cause.
--timeout sets cancellation for command work, except retained Connection operation
budgets (call 60s, test 30s, OAuth 5m) and Publication rollback follow. Omission
preserves operation defaults, including query 135s and unbounded dev/watch.
--deadline (LIMILAKE_DEADLINE) opts into one overall positive budget, including
discovery, requests, retries and polls; an earlier caller or operation deadline wins.
Ordinary deadline failures exit 6. Native processes and structured reports retain
their exits; doctor reports incomplete verification as 10 or observed failure as 1.
--workspace-policy linked (LIMILAKE_WORKSPACE_POLICY) selects explicit CLI input,
then environment, then a linked checkout, then the command default consistently.
The default legacy policy preserves existing omission behavior; explicit legacy
selection emits a deprecation. App, Connection, Execution, Lakehouse, Secret and
Table lists offer --all-workspaces for aggregate results. File and Shortcut lists
use it to find one Lakehouse across Workspaces and list only that target's contents;
ambiguous names fail with a UUID recovery hint. The flag overrides ambient
Workspace defaults, conflicts with explicit --workspace, and refuses any resolved
Workspace-bound credential, including ordinary token sessions. It selects scope,
not pagination; --all still controls paging. Account/local commands keep Workspace
inapplicable.
Legacy Workspace and timeout contracts remain for two subsequent stable releases
and at least 30 days, until an announced breaking release.
After file download/get, -o/--output still names the destination, even if named json;
before the verb it selects table/json/yaml. Prefer --output-file PATH for downloads. update/upgrade --version selects an exact signed release.
--version --check or version --check explicitly checks verified stable metadata (5s maximum).
Ordinary version remains offline; upgrade performs verified atomic replacement.
--error-format json (LIMILAKE_ERROR_FORMAT=json) opts into stable errors with
code, message, hint, and docs_url. stderr is JSON; JSON/YAML stdout mirrors the
error only before output begins, preserving raw streams and existing documents.
It also makes bare-noun help exit 0, with command/purpose/verbs/examples in JSON
or YAML when requested. The default legacy mode retains exit 2 for bare nouns
and prior error presentation. Explicit --error-format legacy and raw/protocol
routes suppress the failure deprecation notice. Retain legacy for two subsequent stable releases
and at least 30 days; removal requires an announced breaking release.

--result-schema v1 (LIMILAKE_RESULT_SCHEMA=v1) selects typed mutation results,
lossless columns/rows for Query and Table read, nullable JSON/YAML Workspace status, and
JSON-line or YAML-document Agent events. Default/explicit legacy preserves prior
stdout and exits for two subsequent stable releases and at least 30 days, until
an announced breaking release. Progress and confirmations use stderr with v1.
Workspace status and Agent session tables retain their existing fields and exits.
Existing structured reads and Build/Ask/setup/doctor documents retain their
schemas; raw downloads, Git and child-process protocols remain unchanged.

--grammar canonical (LIMILAKE_GRAMMAR=canonical) selects explicit verbs for
credential grant, lakehouse schema, billing plan, and billing usage. Default legacy keeps their old arguments/actions.
For example, credential grant list finance still grants the credential named list;
use --grammar canonical credential grant list CREDENTIAL for the read action.
All retained spellings remain supported for two subsequent stable releases and at
least 30 days, until an announced breaking release; deprecations go to stderr.
The old auth switch warning remains on legacy stdout until --result-schema v1.

## limilake

LimiLake -- run functions, query data, and operate Workspaces.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--result-schema` | false | legacy | Opt into typed mutation results, lossless query rows, nullable Workspace status, and Agent event streams. Environment: LIMILAKE_RESULT_SCHEMA. |
| `--error-format` | false | legacy | Opt into stable JSON errors; legacy presentation remains available during migration. Environment: LIMILAKE_ERROR_FORMAT. |
| `--grammar` | false | legacy | Select noun/verb syntax for ambiguous retained leaves; legacy remains the default during migration. Environment: LIMILAKE_GRAMMAR. |
| `--profile` | false | — | Profile selection; auth login writes this profile (default: default). Environment: LIMILAKE_PROFILE. |
| `--workspace` | false | — | Workspace UUID, ref, or name; account/local commands do not use it. Environment: LIMILAKE_WORKSPACE. |
| `--output, -o` | false | table | Output format: table,json,yaml; use --output-file PATH for downloads; retained -o/--output after download selects a path. Environment: LIMILAKE_OUTPUT. |
| `--no-input` | false | false | Suppress prompts and browser opening; explicit stdin is allowed; does not imply --yes. Environment: LIMILAKE_NO_INPUT. |
| `--timeout` | false | — | Positive command budget (e.g. 30s); connection and publication retain their operation timeout. Environment: LIMILAKE_TIMEOUT. |
| `--deadline` | false | — | Positive overall budget including discovery, requests, retries and polling. Environment: LIMILAKE_DEADLINE. |
| `--workspace-policy` | false | legacy | Workspace omission policy; linked selects the checkout consistently, legacy retains command defaults during migration. Environment: LIMILAKE_WORKSPACE_POLICY. |
| `--all-workspaces` | false | false | Aggregate Workspace scope; File/Shortcut keep one Lakehouse. Conflicts with --workspace; requires unbound credentials. |
| `--check` | false | false | Compare verified stable metadata with --version; no automatic installation (5s maximum). |

Use --version --check or version --check for an explicit five-second signed stable-release comparison and the exact upgrade command. Ordinary version output is offline. An available upgrade exits 0; a failed explicit check exits 6. A platform absent from the signed manifest reports unsupported_platform with upgrade_available:false and an empty upgrade_command.

Examples:

```bash
# Inspect available actions
limilake --help
# Inspect actions without local prompts
limilake --no-input --help
```

## limilake add

Add a blank App, Function, or Query to this checkout.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake add --help
# Inspect actions without local prompts
limilake --no-input add --help
```

## limilake add app

Add a Vite React App under apps/&lt;slug&gt;/.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--template` | false | blank | Starter source to add; named templates include a reviewed placeholder Query. |
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `--dry-run` | false | false | Report what would change without writing anything. |
| `SLUG` | false | — | App slug: lowercase letters, digits, and interior hyphens. |

Examples:

```bash
# Example
limilake add app sales-dashboard
# Use without local prompts
limilake --no-input add app sales-dashboard
```

## limilake add function

Add a Python Function at functions/&lt;slug&gt;/function.py.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `--dry-run` | false | false | Report what would change without writing anything. |
| `SLUG` | false | — | Function slug: lowercase letters, digits, and interior hyphens. |

Examples:

```bash
# Example
limilake add function recalculate-invoice
# Use without local prompts
limilake --no-input add function recalculate-invoice
```

## limilake add query

Add a named Query at queries/&lt;slug&gt;.sql with its reviewed schema.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `--dry-run` | false | false | Report what would change without writing anything. |
| `SLUG` | false | — | Query slug: lowercase letters, digits, and interior hyphens. |

Examples:

```bash
# Example
limilake add query active-customers
# Use without local prompts
limilake --no-input add query active-customers
```

## limilake agent

Inspect and drive Workspace Agents.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake agent --help
# Inspect actions without local prompts
limilake --no-input agent --help
```

## limilake agent list

List your Workspace Agents.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--limit` | false | 100 | Maximum Agents to return. |

Bounded result: --limit caps the returned Agents. This API exposes no continuation; a full result does not prove that every Agent was returned.

Examples:

```bash
# Example
limilake agent list
# Use without local prompts
limilake --output=json --no-input agent list
```

## limilake agent messages

Show an Agent's durable Agent Conversation.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `AGENT_ID` | true | — | Agent UUID. |

Examples:

```bash
# Example
limilake agent messages 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input agent messages 11111111-1111-4111-8111-111111111111
```

## limilake agent send

Send one prompt and stream live Agent events.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--agent` | false | — | Existing Agent UUID to continue. |
| `--title` | false | — | Title for a newly-created Agent. |
| `--private, --shared` | false | false | Hide a newly-created Agent from other Workspace members. |
| `PROMPT` | true | — | Prompt to send to the Workspace Agent. |

Use --result-schema v1 with JSON for one event per line, or YAML for separate documents. A terminal completed/error event determines the outcome; interrupted streams fail. Session tokens and raw error diagnostics are omitted. Inspect agent messages before retrying a partial turn. Legacy and table output retain human text and exit behavior.

Examples:

```bash
# Example
limilake agent send 'Summarize the latest available sales data'
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input agent send 'Summarize the latest available sales data'
```

## limilake agent session

Manage an Agent Sandbox Session.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake agent session --help
# Inspect actions without local prompts
limilake --no-input agent session --help
```

## limilake agent session ensure

Ensure a Sandbox Session for an Agent.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `AGENT_ID` | true | — | Agent UUID. |

Examples:

```bash
# Example
limilake agent session ensure 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input agent session ensure 11111111-1111-4111-8111-111111111111
```

## limilake agent session logs

Show the durable Agent Conversation for an Agent Session.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `AGENT_ID` | true | — | Agent UUID. |

Examples:

```bash
# Example
limilake agent session logs 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input agent session logs 11111111-1111-4111-8111-111111111111
```

## limilake agent show

Show one Agent's details.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `AGENT_ID` | true | — | Agent UUID. |

Examples:

```bash
# Example
limilake agent show 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --output=json --no-input agent show 11111111-1111-4111-8111-111111111111
```

## limilake agent view

Deprecated spelling of show; retained during migration.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `AGENT_ID` | true | — | Agent UUID. |

 Deprecated spelling; use agent show. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake agent view 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input agent view 11111111-1111-4111-8111-111111111111
```

## limilake app

Manage data apps (code-first .app.tsx UI items).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake app --help
# Inspect actions without local prompts
limilake --no-input app --help
```

## limilake app list

List apps with their published host, publication state, and last build (optionally scoped to one workspace).

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 50 | Page size (max 100). |

Default: one page selected by --page/--size. --all traverses every server page in batches of 100; do not combine it with --page or --size. A failed later page returns failure without printing a partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

Examples:

```bash
# Example
limilake app list
# Use without local prompts
limilake --output=json --no-input app list --all
```

## limilake app show

Show a single App's details, including its published host, current Build, and Deployment Manifest.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `REFERENCE` | true | — | App UUID, item-id, or name. |

Examples:

```bash
# Example
limilake app show finance-api
# Use without local prompts
limilake --output=json --no-input app show finance-api
```

## limilake ask

Ask a question in plain language and answer it from your data.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--max-steps` | false | 6 | Maximum reasoning steps the service may take. |
| `QUESTION` | true | — | Question to ask in plain language. |

Examples:

```bash
# Example
limilake ask 'What were total sales last month?'
# Use without local prompts
limilake --no-input ask 'What were total sales last month?'
```

## limilake auth

Authenticate and manage access tokens.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake auth --help
# Inspect actions without local prompts
limilake --no-input auth --help
```

## limilake auth login

Acquire credentials and persist only server-derived identity metadata.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--no-wait` | false | false | Print a user verification URL and code, then exit; poll with auth status. |
| `--restart` | false | false | Replace a pending device login; requires --no-wait. |
| `--host` | true | — | Platform host. |
| `--tenant` | false | — | Verified target Tenant UUID or slug. |
| `--token-stdin` | false | false | Read a PAT/bearer from stdin instead of device OAuth. |

Device login asks the user to sign in themselves at the printed URL. Blocking login remains the default. --no-wait prints the user URL/code and pending state, exits 0, and temporarily stages device codes and redeemed access/refresh tokens in a private 0600 file until completion or cleanup. Repeating --no-wait names the retained host/Tenant; a redeemed code reports finalizing with blank URL/code fields. --restart explicitly replaces pending state. Poll with auth status; pending status exits 3 and each call makes at most one due poll. --profile names the destination profile; omission uses default.

Examples:

```bash
# Example
limilake auth login --host=app.limilake.com --profile=work
# Use without local prompts
limilake --no-input auth login --host=app.limilake.com --profile=work --no-wait --output=json
```

## limilake auth logout

Forget the stored token for a profile.

The common flags above are inherited.

Examples:

```bash
# Example
limilake auth logout
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input auth logout
```

## limilake auth setup-git

Install the non-secret Git helper for a profile or environment token.

The common flags above are inherited.

Examples:

```bash
# Example
limilake auth setup-git
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input auth setup-git
```

## limilake auth status

Show the active profile and authenticated user.

The common flags above are inherited.

Resume pending device login with one due poll. Pending state exits 3; successful sign-in atomically saves the profile and clears private pending state. Denial or expiry requires a new auth login. The authenticated status schema is unchanged.

Examples:

```bash
# Example
limilake auth status
# Use without local prompts
limilake --output=json --no-input auth status
```

## limilake auth switch

Deprecated alias for profile use.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `PROFILE` | true | — | Profile to make active. |

Examples:

```bash
# Example
limilake auth switch work
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input auth switch work
```

## limilake auth token

Manage personal access tokens.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake auth token --help
# Inspect actions without local prompts
limilake --no-input auth token --help
```

## limilake auth token create

Create a personal access token (printed once).

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--days` | false | 90 | Validity in days. |
| `NAME` | true | — | Human label for the token. |

Examples:

```bash
# Example
limilake auth token create work
# Use without local prompts
limilake --no-input auth token create work
```

## limilake auth token list

List personal access tokens.

The common flags above are inherited.

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake auth token list
# Use without local prompts
limilake --output=json --no-input auth token list
```

## limilake auth token revoke

Revoke a personal access token.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `TOKEN_ID` | true | — | Token UUID to revoke. |

Examples:

```bash
# Example
limilake auth token revoke 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input auth token revoke 11111111-1111-4111-8111-111111111111
```

## limilake billing

Inspect billing (plan, usage, grants).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake billing --help
# Inspect actions without local prompts
limilake --no-input billing --help
```

## limilake billing grant

Inspect usage grants.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake billing grant --help
# Inspect actions without local prompts
limilake --no-input billing grant --help
```

## limilake billing grant list

List usage grants (quota credits).

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every offset page; --limit sets batch size; do not combine with --offset. |
| `--limit` | false | 50 | Max grants per request; with --all, the size of each batch. |
| `--offset` | false | 0 | Grants to skip. |

Default: one batch selected by --limit/--offset. --all starts at offset zero, uses --limit as batch size, and continues until an empty response. It cannot be combined with --offset. A later failure prints no partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

Examples:

```bash
# Example
limilake billing grant list
# Use without local prompts
limilake --output=json --no-input billing grant list --all
```

## limilake billing grants

List usage grants (quota credits) for the tenant.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every offset page; --limit sets batch size; do not combine with --offset. |
| `--limit` | false | 50 | Max grants per request; with --all, the size of each batch. |
| `--offset` | false | 0 | Grants to skip. |

Default: one batch selected by --limit/--offset. --all starts at offset zero, uses --limit as batch size, and continues until an empty response. It cannot be combined with --offset. A later failure prints no partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

 Deprecated spelling; use billing grant list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake billing grants
# Use without local prompts
limilake --no-input billing grants --all
```

## limilake billing plan

Show the tenant's billing plan, period, and per-resource limits.

The common flags above are inherited.

 Use --grammar canonical to list and select the noun's explicit verbs. Default legacy arguments and actions remain unchanged during the migration window.

Examples:

```bash
# Example
limilake billing plan
# Use without local prompts
limilake --no-input billing plan
```

## limilake billing plan show

Show the Tenant's billing plan and limits.

The common flags above are inherited.

 Select this noun/verb form with --grammar canonical. The default legacy syntax remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake --grammar=canonical billing plan show
# Use without local prompts
limilake --grammar=canonical --output=json --no-input billing plan show
```

## limilake billing usage

List metered usage ledger entries for the tenant.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every offset page; --limit sets batch size; do not combine with --offset. |
| `--meter` | false | — | Filter by meter code. |
| `--resource` | false | — | Filter by resource id. |
| `--since` | false | — | Only entries at/after this time. |
| `--until` | false | — | Only entries before this time. |
| `--limit` | false | 50 | Max entries per request; with --all, the size of each batch. |
| `--offset` | false | 0 | Entries to skip. |

Default: one batch selected by --limit/--offset. --all starts at offset zero, uses --limit as batch size, and continues until an empty response. It cannot be combined with --offset. A later failure prints no partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

 Use --grammar canonical to list and select the noun's explicit verbs. Default legacy arguments and actions remain unchanged during the migration window.

Examples:

```bash
# Example
limilake billing usage
# Use without local prompts
limilake --no-input billing usage --all
```

## limilake billing usage list

List metered usage ledger entries.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every offset page; --limit sets batch size; do not combine with --offset. |
| `--meter` | false | — | Filter by meter code. |
| `--resource` | false | — | Filter by resource id. |
| `--since` | false | — | Only entries at/after this time. |
| `--until` | false | — | Only entries before this time. |
| `--limit` | false | 50 | Max entries per request; with --all, the size of each batch. |
| `--offset` | false | 0 | Entries to skip. |

Default: one batch selected by --limit/--offset. --all starts at offset zero, uses --limit as batch size, and continues until an empty response. It cannot be combined with --offset. A later failure prints no partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

 Select this noun/verb form with --grammar canonical. The default legacy syntax remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake --grammar=canonical billing usage list
# Use without local prompts
limilake --grammar=canonical --output=json --no-input billing usage list --all
```

## limilake build

Build the Workspace through the shared Build Engine and emit its Build Manifest.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--out` | false | — | Write artifacts and the Build Manifest to this directory instead of &lt;root&gt;/.limilake/build. |
| `--source-sha` | false | — | Record this exact Git revision identity in the Build Manifest. |
| `--offline` | false | false | Use only the verified managed toolchain cache and local pnpm store; do not acquire or mutate managed packages. |
| `ROOT` | false | . | Workspace root directory to build. |

Build emits its Build Manifest to stdout and step logs to stderr regardless of the output flag.

Examples:

```bash
# Example
limilake build
# Use without local prompts
limilake --no-input build
```

## limilake completion

Print static shell completion for Bash, Zsh, or Fish.

The common flags above are inherited.

Print a static shell script from the command metadata. Bash: source <(limilake completion bash). Zsh: run autoload -Uz compinit; compinit, then source <(limilake completion zsh). Fish: limilake completion fish | source. Regenerate after upgrading. No credentials, network calls, CLI subprocesses or shell-profile edits; shell-script stdout remains raw regardless of --output.

Examples:

```bash
# Inspect available actions
limilake completion --help
# Inspect actions without local prompts
limilake --no-input completion --help
```

## limilake completion bash

Print static Bash completion; source it in your shell.

The common flags above are inherited.

Print a static shell script from the command metadata. Bash: source <(limilake completion bash). Zsh: run autoload -Uz compinit; compinit, then source <(limilake completion zsh). Fish: limilake completion fish | source. Regenerate after upgrading. No credentials, network calls, CLI subprocesses or shell-profile edits; shell-script stdout remains raw regardless of --output.

Examples:

```bash
# Example
limilake completion bash
# Use without local prompts
limilake --no-input completion bash
```

## limilake completion fish

Print static Fish completion; source it in your shell.

The common flags above are inherited.

Print a static shell script from the command metadata. Bash: source <(limilake completion bash). Zsh: run autoload -Uz compinit; compinit, then source <(limilake completion zsh). Fish: limilake completion fish | source. Regenerate after upgrading. No credentials, network calls, CLI subprocesses or shell-profile edits; shell-script stdout remains raw regardless of --output.

Examples:

```bash
# Example
limilake completion fish
# Use without local prompts
limilake --no-input completion fish
```

## limilake completion zsh

Print static Zsh completion; load after compinit.

The common flags above are inherited.

Print a static shell script from the command metadata. Bash: source <(limilake completion bash). Zsh: run autoload -Uz compinit; compinit, then source <(limilake completion zsh). Fish: limilake completion fish | source. Regenerate after upgrading. No credentials, network calls, CLI subprocesses or shell-profile edits; shell-script stdout remains raw regardless of --output.

Examples:

```bash
# Example
limilake completion zsh
# Use without local prompts
limilake --no-input completion zsh
```

## limilake config

Manage CLI profiles and local configuration.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake config --help
# Inspect actions without local prompts
limilake --no-input config --help
```

## limilake config get

Read a config value, or dump the resolved profile and link.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `KEY` | false | — | Config key: host, tenant, or active. |

Examples:

```bash
# Example
limilake config get
# Use without local prompts
limilake --no-input config get
```

## limilake config list

Compatibility alias for profile list.

The common flags above are inherited.

Complete local profile configuration; no API request or remote pagination.

 Deprecated spelling; use profile list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake config list
# Use without local prompts
limilake --output=json --no-input config list
```

## limilake config set

Set host or active profile; Tenant authority is server-owned.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `KEY` | true | — | Config key. |
| `VALUE` | true | — | Value to set. |

Examples:

```bash
# Example
limilake config set host app.limilake.com --profile=work
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input config set host app.limilake.com --profile=work
```

## limilake connection

Manage workspace connections (provider-bound or custom credentials).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake connection --help
# Inspect actions without local prompts
limilake --no-input connection --help
```

## limilake connection authorize

Authorize an existing OAuth Connection through the Setup Contract lifecycle.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--scope` | false | — | OAuth scope (repeatable; custom scopes are allowed). |
| `--no-browser` | false | false | Print OAuth URL instead of opening a browser. |
| `REFERENCE` | true | — | Connection id or stable ref. |

Examples:

```bash
# Example
limilake connection authorize finance-api
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input connection authorize finance-api
```

## limilake connection call

Call a Connection through the credential-injecting, SSRF-bounded gateway.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--fail` | false | false | Exit 1 on a non-2xx response; omission retains exit 0 for HTTP failures. |
| `--method` | true | — | Explicit HTTP method. |
| `--path` | true | — | Upstream-relative path beginning with /; no query or fragment. Use --query for parameters. |
| `--query` | false | — | Query key=value (repeatable). |
| `--header` | false | — | Non-credential header name:value (repeatable). |
| `--input` | false | — | JSON, @file, or - for standard input. |
| `--output-file` | false | — | Write provider response bytes to a file. |
| `--max-bytes` | false | 10485760 | Maximum request and response size. |
| `REFERENCE` | true | — | Connection id or stable ref. |

Keep query data in repeatable --query key=value options. Quote shell metacharacters, for example --query '$top=1'. Fragments are refused. HTTP errors retain their response and exit 0 unless --fail is supplied. --fail exits 1 after rendering the same response, without a second document.

Examples:

```bash
# Example
limilake connection call graph --workspace=finance --method=GET --path=/users '--query=$top=1' --fail
# Use without local prompts
limilake --no-input connection call graph --workspace=finance --method=GET --path=/users '--query=$top=1' --fail
```

## limilake connection create

Create a catalog or Custom Connection through the canonical setup lifecycle.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--provider` | false | — | Catalog provider id. |
| `--custom` | false | false | Create a bounded Custom Connection. |
| `--name` | false | — | Connection display name. |
| `--ref` | false | — | Stable Workspace-unique Connection ref. |
| `--auth-method` | false | — | Setup Contract authentication option. |
| `--field` | false | — | Submit key=value (repeatable). Prefer --values-from - or hidden prompts for secrets. |
| `--values-policy` | false | legacy | Input validation policy; strict rejects duplicate and overlapping values. |
| `--values-from` | false | — | Read a JSON object from @file or standard input (-). |
| `--base-url` | false | — | Custom upstream HTTPS base URL. |
| `--allowed-host` | false | — | Custom SSRF allowlist host (repeatable). |
| `--inject-header` | false | — | Inject an API key into this header. |
| `--inject-query` | false | — | Inject an API key into this query parameter. |
| `--scope` | false | — | OAuth scope (repeatable; custom scopes are allowed). |
| `--no-browser` | false | false | Print OAuth URL instead of opening a browser. |

Supply the provider's requested setup fields through stdin with --values-policy strict. Default legacy decoding and last-value precedence remain available through two subsequent stable releases and at least 30 days, until an announced breaking release. Keep secrets out of shell arguments and history. OAuth authorization belongs to the person who signs in.

Examples:

```bash
# Example
limilake connection create --provider=aws-s3 --workspace=finance --values-from=- --values-policy=strict --no-input < private-connection.json
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input connection create --provider=aws-s3 --workspace=finance --values-from=- --values-policy=strict --no-input < private-connection.json
```

## limilake connection delete

Soft-delete a Connection after explicit confirmation.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Confirm deletion. |
| `REFERENCE` | true | — | Connection id or stable ref. |

Examples:

```bash
# Example
limilake connection delete finance-api
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input connection delete finance-api --yes
```

## limilake connection list

List connections for a workspace, or across every membership when omitted.

The common flags above are inherited.

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake connection list
# Use without local prompts
limilake --output=json --no-input connection list
```

## limilake connection move

Move an active Connection to another Workspace while preserving its ref and authorization.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--to-workspace` | true | — | Destination Workspace (UUID/slug/name). |
| `REFERENCE` | true | — | Connection id or stable ref. |

Examples:

```bash
# Example
limilake connection move finance-api --to-workspace=example
# Use without local prompts
limilake --no-input connection move finance-api --to-workspace=example
```

## limilake connection provider

Inspect server-owned Connection Setup Contracts.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake connection provider --help
# Inspect actions without local prompts
limilake --no-input connection provider --help
```

## limilake connection provider list

List catalog providers and their safe setup capabilities.

The common flags above are inherited.

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake connection provider list
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input connection provider list
```

## limilake connection provider show

Show the canonical Setup Contract for one provider.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `PROVIDER` | true | — | Catalog provider id. |

Provider IDs come from live discovery. An unambiguous nearby ID is suggested after not-found; the CLI never substitutes it or retries automatically.

Examples:

```bash
# Example
limilake connection provider show aws-s3
# Use without local prompts
limilake --output=json --no-input connection provider show aws-s3
```

## limilake connection reauthorize

Replace revoked/expired OAuth grants while preserving the Connection ref.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--scope` | false | — | OAuth scope (repeatable; custom scopes are allowed). |
| `--no-browser` | false | false | Print OAuth URL instead of opening a browser. |
| `REFERENCE` | true | — | Connection id or stable ref. |

Examples:

```bash
# Example
limilake connection reauthorize finance-api
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input connection reauthorize finance-api
```

## limilake connection show

Show a single connection by id, ref (slug), name, or display name.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `REFERENCE` | true | — | Connection id, ref (slug), name, or display name. |

Examples:

```bash
# Example
limilake connection show finance-api
# Use without local prompts
limilake --output=json --no-input connection show finance-api
```

## limilake connection test

Test a Connection using retained base-path mode or authenticated provider probes.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--probe` | false | legacy | Provider mode verifies authentication; legacy retains GET / and HTTP exit semantics during migration. |
| `--bucket` | false | — | S3 bucket for the provider probe (max-keys=1); requires --probe provider. |
| `REFERENCE` | true | — | Connection id or stable ref. |

Use --probe provider for fresh authenticated egress evidence; S3 requires --bucket. The Graph service document (16 KiB maximum) proves connectivity only, followed by at most one scope-compatible authenticated probe. Reports contain no provider bodies. Exit 0 means healthy, 1 means a failed probe, 2 means required bucket input, and 9 means authentication health is unknown. Omission or --probe legacy preserves GET /, its response schema, and HTTP exit behavior for two subsequent stable releases and at least 30 days, until an announced breaking release.

Examples:

```bash
# Example
limilake connection test enreach_s3 --workspace=finance --probe=provider --bucket=finance-data
# Use without local prompts
limilake --no-input connection test enreach_s3 --workspace=finance --probe=provider --bucket=finance-data
```

## limilake connection update

Update non-OAuth metadata or static secrets while preserving identity and grants.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--name` | false | — | Replace the display name; preserve the code-facing ref. |
| `--base-url` | false | — | Replace a custom Connection's HTTPS base URL. |
| `--allowed-host` | false | — | Replace the complete custom host allowlist (repeatable). |
| `--inject-header` | false | — | Replace a custom API-key injection header name. |
| `--field` | false | — | Non-secret metadata key=value (repeatable). Secret fields require stdin. |
| `--values-from` | false | — | Read one bounded JSON object from stdin (-); files and inline secrets are refused. |
| `REFERENCE` | true | — | Credential or Connection UUID, stable ref, or name. |

Update non-OAuth credentials in place. Secrets require bounded JSON stdin via --values-from -; --field accepts declared non-secret metadata only. Files, inline JSON, duplicate keys, overlapping inputs and empty updates are rejected. Omitted fields remain unchanged; repeated --allowed-host replaces the entire custom allowlist. Catalog routing cannot be overridden. A live revision check rejects concurrent changes without retrying. Results contain credential_id, nullable workspace_id, ref, name, revision and affected_grants; shared credentials retain every grant. Connection updates require linked/selected Workspace context. Direct Credential updates retain Tenant scope on legacy omission; --workspace, its environment fallback, or --workspace-policy linked selects Workspace scope. Conflicting Workspace environment defaults require explicit --workspace. OAuth uses connection reauthorize.

Examples:

```bash
# Example
limilake connection update storage --workspace=finance --values-from=- < private-connection.json
# Use without local prompts
limilake --no-input connection update storage --workspace=finance --values-from=- < private-connection.json
```

## limilake context

Show the effective profile, identity, Tenant, Workspace, and credential.

The common flags above are inherited.

Examples:

```bash
# Example
limilake context
# Use without local prompts
limilake --no-input context
```

## limilake credential

Manage credentials (list/grant/revoke).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake credential --help
# Inspect actions without local prompts
limilake --no-input credential --help
```

## limilake credential grant

Grant a credential to a workspace so its code can use the secret.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `CREDENTIAL` | true | — | Credential UUID, ref (slug), or name. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or name. |

 Use --grammar canonical to list and select the noun's explicit verbs. Default legacy arguments and actions remain unchanged during the migration window.

Examples:

```bash
# Example
limilake credential grant finance-api finance
# Use without local prompts
limilake --no-input credential grant finance-api finance
```

## limilake credential grant create

Grant a credential to a Workspace.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `CREDENTIAL` | true | — | Credential UUID, ref (slug), or name. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or name. |

 Select this noun/verb form with --grammar canonical. The default legacy syntax remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake --grammar=canonical credential grant create finance-api finance
# Use without local prompts
limilake --grammar=canonical --no-input credential grant create finance-api finance
```

## limilake credential grant delete

Revoke a credential's Workspace grant.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes, -y` | false | false | Skip the confirmation prompt. |
| `CREDENTIAL` | true | — | Credential UUID, ref (slug), or name. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or name (grant target). |

 Select this noun/verb form with --grammar canonical. The default legacy syntax remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake --grammar=canonical credential grant delete finance-api finance
# Use without local prompts
limilake --grammar=canonical --no-input credential grant delete finance-api finance --yes
```

## limilake credential grant list

List a credential's Workspace grants.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `CREDENTIAL` | true | — | Credential UUID, ref (slug), or name. |

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

 Select this noun/verb form with --grammar canonical. The default legacy syntax remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake --grammar=canonical credential grant list finance-api
# Use without local prompts
limilake --grammar=canonical --output=json --no-input credential grant list finance-api
```

## limilake credential grants

List the workspace grants for a credential.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `CREDENTIAL` | true | — | Credential UUID, ref (slug), or name. |

 Deprecated spelling; use --grammar canonical credential grant list CREDENTIAL. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake credential grants finance-api
# Use without local prompts
limilake --no-input credential grants finance-api
```

## limilake credential list

List credentials in the tenant (config is always redacted).

The common flags above are inherited.

Every credential page is read by default.

Examples:

```bash
# Example
limilake credential list
# Use without local prompts
limilake --output=json --no-input credential list
```

## limilake credential revoke

Revoke a credential's grant from a workspace.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes, -y` | false | false | Skip the confirmation prompt. |
| `CREDENTIAL` | true | — | Credential UUID, ref (slug), or name. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or name (grant target). |

 Deprecated spelling; use --grammar canonical credential grant delete CREDENTIAL WORKSPACE. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake credential revoke finance-api finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input credential revoke finance-api finance --yes
```

## limilake credential update

Update non-OAuth metadata or static secrets while preserving identity and grants.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--name` | false | — | Replace the display name; preserve the code-facing ref. |
| `--base-url` | false | — | Replace a custom Connection's HTTPS base URL. |
| `--allowed-host` | false | — | Replace the complete custom host allowlist (repeatable). |
| `--inject-header` | false | — | Replace a custom API-key injection header name. |
| `--field` | false | — | Non-secret metadata key=value (repeatable). Secret fields require stdin. |
| `--values-from` | false | — | Read one bounded JSON object from stdin (-); files and inline secrets are refused. |
| `REFERENCE` | true | — | Credential or Connection UUID, stable ref, or name. |

Update non-OAuth credentials in place. Secrets require bounded JSON stdin via --values-from -; --field accepts declared non-secret metadata only. Files, inline JSON, duplicate keys, overlapping inputs and empty updates are rejected. Omitted fields remain unchanged; repeated --allowed-host replaces the entire custom allowlist. Catalog routing cannot be overridden. A live revision check rejects concurrent changes without retrying. Results contain credential_id, nullable workspace_id, ref, name, revision and affected_grants; shared credentials retain every grant. Connection updates require linked/selected Workspace context. Direct Credential updates retain Tenant scope on legacy omission; --workspace, its environment fallback, or --workspace-policy linked selects Workspace scope. Conflicting Workspace environment defaults require explicit --workspace. OAuth uses connection reauthorize.

Examples:

```bash
# Example
limilake credential update storage --values-from=- < private-connection.json
# Use without local prompts
limilake --no-input credential update storage --values-from=- < private-connection.json
```

## limilake dev

Run the local Workspace development loop (Vite Apps, Function processes, diagnostics).

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse` | false | — | Optional default Lakehouse for named Queries. The full linked-Workspace catalog is always exposed; a sole Lakehouse is automatic. |
| `--host` | false | 127.0.0.1 | Specific interface address or hostname for App previews and the broker/Studio listener. Remote exposure is deliberate; wildcard addresses are refused. |
| `--port` | false | — | Dev-server port for the broker and Studio Protocol. Defaults to an ephemeral port. |
| `--app-port-base` | false | — | First port in the deterministic range of stable App ports. Remote hosts default to 4301; loopback keeps ephemeral ports unless set. |
| `--no-browser` | false | false | Print the Local Studio URL without opening a browser. |
| `--no-functions` | false | false | Start Apps and the local broker without supervising HTTP Functions. |
| `--managed` | false | false | Run the existing development supervisor in managed mode using the platform-provided launch file; never opens or writes Local Studio discovery. |
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |

This long-running or streamed command retains its own output protocol. Record output flags do not turn child or streamed output into a single JSON document.

Examples:

```bash
# Example
limilake dev
# Use without local prompts
limilake --no-input dev
```

## limilake docs

Read bundled documentation without a network connection.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--raw` | false | false | Print raw Markdown. |
| `TOPIC` | false | — | Topic to print. Omit to list available topics. |

Examples:

```bash
# Example
limilake docs getting-started
# Use without local prompts
limilake --no-input docs getting-started
```

## limilake doctor

Check authentication, checkout, connections, toolchain, and CLI release without repairs.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--offline` | false | false | Skip network probes; inspect local metadata without repairs. |
| `--connection` | false | — | Probe selected Connection refs (repeatable, at most 20); omission selects up to 20 in the Workspace. |
| `--bucket` | false | — | S3 bucket for authenticated Connection probes; select its Connection with --connection. |
| `--python` | false | false | Inspect Function Python imports and installed optional capability closures without authentication or executing Workspace code. |

Read-only schema-1 diagnostics include healthy and report/per-check complete, profile/token metadata, checkout and live Workspace authority, Git/helper configuration, Connections, managed toolchain/applicable Proto, and signed stable release comparison. --offline skips network work and remains unverified. The overall budget is 45s; ordinary probes get 5s, Git helper/toolchain 10s, and Connections 35s including two shared discovery phases and five waves of four observations. Provider calls get 4s inside each 5s observation, excluding discovery/session minting; an earlier --timeout wins. No refresh, pending-login redemption, helper execution, installation or repairs. Omission selects at most 20 Connections in the linked/explicit Workspace; repeat --connection for a smaller set and add --bucket for S3. Observed failures exit 1; otherwise incomplete or unverified reports exit 10, including offline mode, truncation and unsupported authentication. Verified completion exits 0, including informative upgrade warnings. Table output prints the overall verdict and exit code; ambiguous or unknown Connection refs remain unverified input. Confirmed failures survive a late observation deadline. Outside a checkout, Workspace checks are skipped unless --workspace is supplied.

Examples:

```bash
# Example
limilake doctor --offline
# Use without local prompts
limilake --no-input doctor --offline
```

## limilake execution

Inspect execution history.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake execution --help
# Inspect actions without local prompts
limilake --no-input execution --help
```

## limilake execution cancel

Cancel a live execution and its linked sandbox.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

Examples:

```bash
# Example
limilake execution cancel 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input execution cancel 11111111-1111-4111-8111-111111111111
```

## limilake execution list

List recent executions.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 50 | Page size. |

Default: one page selected by --page/--size. --all traverses every server page in batches of 100; do not combine it with --page or --size. A failed later page returns failure without printing a partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

Examples:

```bash
# Example
limilake execution list
# Use without local prompts
limilake --output=json --no-input execution list --all
```

## limilake execution logs

Show an execution's captured log lines.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--limit` | false | 200 | Maximum log lines per page. |
| `EXECUTION_ID` | true | — | Execution UUID. |

All log pages are read using the server's next offset. --limit is the per-page size.

Examples:

```bash
# Example
limilake execution logs 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input execution logs 11111111-1111-4111-8111-111111111111
```

## limilake execution show

Show one execution's details.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

Examples:

```bash
# Example
limilake execution show 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --output=json --no-input execution show 11111111-1111-4111-8111-111111111111
```

## limilake execution view

Deprecated spelling of show; retained during migration.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution show. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake execution view 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input execution view 11111111-1111-4111-8111-111111111111
```

## limilake execution watch

Poll an execution until terminal.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

Examples:

```bash
# Example
limilake execution watch 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input execution watch 11111111-1111-4111-8111-111111111111
```

## limilake explain

Explain a push rejection code and its fix without a network connection.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `CODE` | true | — | Stable rejection code printed by Git or the CLI. |

Examples:

```bash
# Example
limilake explain git_ref_not_allowed
# Use without local prompts
limilake --no-input explain git_ref_not_allowed
```

## limilake file

List, download, upload, and delete files inside a Lakehouse.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake file --help
# Inspect actions without local prompts
limilake --no-input file --help
```

## limilake file delete

Delete a file after explicit confirmation.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Confirm deletion. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `FILE_ID` | true | — | File UUID. |

Examples:

```bash
# Example
limilake file delete finance 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input file delete finance 11111111-1111-4111-8111-111111111111 --yes
```

## limilake file download

Download content for a file inside a Lakehouse via a presigned URL.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--output-file` | false | — | Write bytes to this path; select --result-schema v1 and -o json before file for download metadata. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `FILE_ID` | true | — | File UUID. |
| `--output, -o` | false | — | Legacy destination after download/get; prefer --output-file PATH. Format flags go before file; LIMILAKE_OUTPUT always selects the format. |

Use --output-file PATH to save bytes; paths expand ~ like other output-file options. Select --result-schema v1 and put -o json before file for {schema_version:1,action:file.download,result:{file_id,output_file,size_bytes}} (YAML uses the same mapping). Legacy result selection retains the prose acknowledgement and emits a stderr deprecation. After download/get, legacy -o/--output still means a path (including json and a quoted ~ kept literally), with a stderr deprecation for two subsequent stable releases and at least 30 days until an announced breaking release. Conflicting destinations, including an explicit empty legacy destination requesting raw stdout, fail before any request. LIMILAKE_OUTPUT always selects format, never destination. Legacy invocations without a destination retain exact stdout bytes regardless of format; structured metadata requires --output-file. A path named - is a literal file. With --error-format json, metadata-mode failures mirror the stable error on JSON/YAML stdout; raw stdout failures keep errors on stderr.

Examples:

```bash
# Example
limilake file download finance 11111111-1111-4111-8111-111111111111 --output-file=report.csv
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input file download finance 11111111-1111-4111-8111-111111111111 --output-file=report.csv
```

## limilake file get

Download content for a file inside a Lakehouse via a presigned URL.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--output-file` | false | — | Write bytes to this path; select --result-schema v1 and -o json before file for download metadata. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `FILE_ID` | true | — | File UUID. |
| `--output, -o` | false | — | Legacy destination after download/get; prefer --output-file PATH. Format flags go before file; LIMILAKE_OUTPUT always selects the format. |

Use --output-file PATH to save bytes; paths expand ~ like other output-file options. Select --result-schema v1 and put -o json before file for {schema_version:1,action:file.download,result:{file_id,output_file,size_bytes}} (YAML uses the same mapping). Legacy result selection retains the prose acknowledgement and emits a stderr deprecation. After download/get, legacy -o/--output still means a path (including json and a quoted ~ kept literally), with a stderr deprecation for two subsequent stable releases and at least 30 days until an announced breaking release. Conflicting destinations, including an explicit empty legacy destination requesting raw stdout, fail before any request. LIMILAKE_OUTPUT always selects format, never destination. Legacy invocations without a destination retain exact stdout bytes regardless of format; structured metadata requires --output-file. A path named - is a literal file. With --error-format json, metadata-mode failures mirror the stable error on JSON/YAML stdout; raw stdout failures keep errors on stderr. Deprecated spelling; use file download. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake file get finance 11111111-1111-4111-8111-111111111111 --output-file=report.csv
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input file get finance 11111111-1111-4111-8111-111111111111 --output-file=report.csv
```

## limilake file list

List files stored in a Lakehouse.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 100 | Page size (1–100). |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

Default: the first 100 files requested by the CLI. --page/--size select a server page; --all traverses server pages in batches of 100. Do not combine --all with --page or --size. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure.

Examples:

```bash
# Example
limilake file list finance
# Use without local prompts
limilake --output=json --no-input file list finance --all
```

## limilake file ls

List files stored in a Lakehouse.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 100 | Page size (1–100). |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

Default: the first 100 files requested by the CLI. --page/--size select a server page; --all traverses server pages in batches of 100. Do not combine --all with --page or --size. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure.

 Deprecated spelling; use file list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake file ls finance
# Use without local prompts
limilake --no-input file ls finance --all
```

## limilake file put

Upload a local file into a Lakehouse.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--path` | false | — | Destination path within the Lakehouse files area. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `SOURCE` | true | — | Local file to upload. |

 Deprecated spelling; use file upload. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake file put finance report.csv
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input file put finance report.csv
```

## limilake file upload

Upload a local file into a Lakehouse.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--path` | false | — | Destination path within the Lakehouse files area. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `SOURCE` | true | — | Local file to upload. |

Examples:

```bash
# Example
limilake file upload finance report.csv
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input file upload finance report.csv
```

## limilake function

Manage Workspace Functions.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake function --help
# Inspect actions without local prompts
limilake --no-input function --help
```

## limilake function commit

Commit named local Function files through a Workspace commit.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--message, -m` | false | Deploy functions via CLI | Commit message. |
| `--branch` | false | main | Target branch. |
| `PATHS` | true | — | Local Function files to commit. |

Examples:

```bash
# Example
limilake function commit functions/recalculate-invoice/function.py
# Use without local prompts
limilake --no-input function commit functions/recalculate-invoice/function.py
```

## limilake function deploy

Deprecated spelling of commit; retained during migration.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--message, -m` | false | Deploy functions via CLI | Commit message. |
| `--branch` | false | main | Target branch. |
| `PATHS` | true | — | Local Function files to commit. |

 Deprecated spelling; use function commit. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake function deploy functions/recalculate-invoice/function.py
# Use without local prompts
limilake --no-input function deploy functions/recalculate-invoice/function.py
```

## limilake function invoke

Invoke a Function server-side or in the local Workspace runtime.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--input` | false | — | JSON object as run input or HTTP body; pass - to read stdin. |
| `--local` | false | false | Run in the Workspace runtime instead of the live sandbox. |
| `--branch` | false | main | Git branch for action or sync dispatch. |
| `--handler` | false | — | Deliberate handler to run: action or sync. Required when the Function declares both. |
| `--path` | false | — | HTTP Function route; inferred for a single-route Function. |
| `--method` | false | — | HTTP Function method; inferred for a single-route Function. |
| `--query` | false | — | HTTP query key=value; repeatable. |
| `FUNCTION` | true | — | Function name or item-id (ULID). |

Examples:

```bash
# Example
limilake function invoke recalculate-invoice
# Use without local prompts
limilake --no-input function invoke recalculate-invoice
```

## limilake function list

List functions across the Workspaces you can read.

The common flags above are inherited.

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake function list
# Use without local prompts
limilake --output=json --no-input function list
```

## limilake function logs

Show recent Function Runs.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--limit` | false | 20 | Number of Function Runs to show. |
| `FUNCTION_PATH` | true | — | Function repository path. |

Bounded result: --limit caps returned Function Runs. This command exposes no continuation.

Examples:

```bash
# Example
limilake function logs functions/recalculate-invoice/function.py
# Use without local prompts
limilake --no-input function logs functions/recalculate-invoice/function.py
```

## limilake function serve

Serve Functions through the Workspace-pinned runtime.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--schedules` | false | false | Also run scheduled triggers locally. |
| `PATH` | false | — | Function file or directory; defaults to the whole Workspace. |

This long-running or streamed command retains its own output protocol. Record output flags do not turn child or streamed output into a single JSON document.

Examples:

```bash
# Example
limilake function serve
# Use without local prompts
limilake --no-input function serve
```

## limilake function show

Show a Function's configuration.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `FUNCTION_PATH` | true | — | Function repository path. |

Examples:

```bash
# Example
limilake function show functions/recalculate-invoice/function.py
# Use without local prompts
limilake --output=json --no-input function show functions/recalculate-invoice/function.py
```

## limilake function trigger

Simulate Function triggers.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake function trigger --help
# Inspect actions without local prompts
limilake --no-input function trigger --help
```

## limilake function trigger fire

Enqueue a schedule-attributed Function Run.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--input` | false | — | JSON object as run input; pass - to read stdin. |
| `--branch` | false | main | Git branch to dispatch. |
| `--handler` | false | — | Deliberate handler to run: action or sync. Required when the Function declares both. |
| `FUNCTION` | true | — | Function name or item-id (ULID). |

Examples:

```bash
# Example
limilake function trigger fire recalculate-invoice
# Use without local prompts
limilake --no-input function trigger fire recalculate-invoice
```

## limilake function watch

Poll one Function Run until terminal.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `FUNCTION_PATH` | true | — | Function repository path (for example functions/daily/function.py). |
| `RUN_ID` | true | — | Function Run UUID. |

Examples:

```bash
# Example
limilake function watch functions/recalculate-invoice/function.py 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input function watch functions/recalculate-invoice/function.py 11111111-1111-4111-8111-111111111111
```

## limilake generate

Regenerate committed Workspace clients from local source.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `--check` | false | false | Check for generated-client drift without writing anything. |

Examples:

```bash
# Example
limilake generate
# Use without local prompts
limilake --no-input generate
```

## limilake job

Inspect execution history.

Retained compatibility spelling.

The common flags above are inherited.

 Deprecated spelling; use execution. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Inspect available actions
limilake job --help
# Inspect actions without local prompts
limilake --no-input job --help
```

## limilake job cancel

Cancel a live execution and its linked sandbox.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution cancel. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake job cancel 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input job cancel 11111111-1111-4111-8111-111111111111
```

## limilake job list

List recent executions.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 50 | Page size. |

Default: one page selected by --page/--size. --all traverses every server page in batches of 100; do not combine it with --page or --size. A failed later page returns failure without printing a partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

 Deprecated spelling; use execution list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake job list
# Use without local prompts
limilake --output=json --no-input job list --all
```

## limilake job logs

Show an execution's captured log lines.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--limit` | false | 200 | Maximum log lines per page. |
| `EXECUTION_ID` | true | — | Execution UUID. |

All log pages are read using the server's next offset. --limit is the per-page size.

 Deprecated spelling; use execution logs. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake job logs 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input job logs 11111111-1111-4111-8111-111111111111
```

## limilake job show

Show one execution's details.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution show. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake job show 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --output=json --no-input job show 11111111-1111-4111-8111-111111111111
```

## limilake job view

Deprecated spelling of show; retained during migration.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution show. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake job view 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input job view 11111111-1111-4111-8111-111111111111
```

## limilake job watch

Poll an execution until terminal.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution watch. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake job watch 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input job watch 11111111-1111-4111-8111-111111111111
```

## limilake lake

Query tables and manage files inside Lakehouses.

Retained compatibility spelling.

The common flags above are inherited.

 Deprecated spelling; use query, table, or file. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Inspect available actions
limilake lake --help
# Inspect actions without local prompts
limilake --no-input lake --help
```

## limilake lake file

List, download, upload, and delete files inside a Lakehouse.

Retained compatibility spelling.

The common flags above are inherited.

 Deprecated spelling; use file. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Inspect available actions
limilake lake file --help
# Inspect actions without local prompts
limilake --no-input lake file --help
```

## limilake lake file delete

Delete a file after explicit confirmation.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Confirm deletion. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `FILE_ID` | true | — | File UUID. |

 Deprecated spelling; use file delete. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake file delete finance 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input lake file delete finance 11111111-1111-4111-8111-111111111111 --yes
```

## limilake lake file download

Download content for a file inside a Lakehouse via a presigned URL.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--output-file` | false | — | Write bytes to this path; select --result-schema v1 and -o json before file for download metadata. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `FILE_ID` | true | — | File UUID. |
| `--output, -o` | false | — | Legacy destination after download/get; prefer --output-file PATH. Format flags go before file; LIMILAKE_OUTPUT always selects the format. |

Use --output-file PATH to save bytes; paths expand ~ like other output-file options. Select --result-schema v1 and put -o json before file for {schema_version:1,action:file.download,result:{file_id,output_file,size_bytes}} (YAML uses the same mapping). Legacy result selection retains the prose acknowledgement and emits a stderr deprecation. After download/get, legacy -o/--output still means a path (including json and a quoted ~ kept literally), with a stderr deprecation for two subsequent stable releases and at least 30 days until an announced breaking release. Conflicting destinations, including an explicit empty legacy destination requesting raw stdout, fail before any request. LIMILAKE_OUTPUT always selects format, never destination. Legacy invocations without a destination retain exact stdout bytes regardless of format; structured metadata requires --output-file. A path named - is a literal file. With --error-format json, metadata-mode failures mirror the stable error on JSON/YAML stdout; raw stdout failures keep errors on stderr. Deprecated spelling; use file download. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake file download finance 11111111-1111-4111-8111-111111111111 --output-file=report.csv
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input lake file download finance 11111111-1111-4111-8111-111111111111 --output-file=report.csv
```

## limilake lake file get

Download content for a file inside a Lakehouse via a presigned URL.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--output-file` | false | — | Write bytes to this path; select --result-schema v1 and -o json before file for download metadata. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `FILE_ID` | true | — | File UUID. |
| `--output, -o` | false | — | Legacy destination after download/get; prefer --output-file PATH. Format flags go before file; LIMILAKE_OUTPUT always selects the format. |

Use --output-file PATH to save bytes; paths expand ~ like other output-file options. Select --result-schema v1 and put -o json before file for {schema_version:1,action:file.download,result:{file_id,output_file,size_bytes}} (YAML uses the same mapping). Legacy result selection retains the prose acknowledgement and emits a stderr deprecation. After download/get, legacy -o/--output still means a path (including json and a quoted ~ kept literally), with a stderr deprecation for two subsequent stable releases and at least 30 days until an announced breaking release. Conflicting destinations, including an explicit empty legacy destination requesting raw stdout, fail before any request. LIMILAKE_OUTPUT always selects format, never destination. Legacy invocations without a destination retain exact stdout bytes regardless of format; structured metadata requires --output-file. A path named - is a literal file. With --error-format json, metadata-mode failures mirror the stable error on JSON/YAML stdout; raw stdout failures keep errors on stderr. Deprecated spelling; use file download. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake file get finance 11111111-1111-4111-8111-111111111111 --output-file=report.csv
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input lake file get finance 11111111-1111-4111-8111-111111111111 --output-file=report.csv
```

## limilake lake file list

List files stored in a Lakehouse.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 100 | Page size (1–100). |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

Default: the first 100 files requested by the CLI. --page/--size select a server page; --all traverses server pages in batches of 100. Do not combine --all with --page or --size. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure.

 Deprecated spelling; use file list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake file list finance
# Use without local prompts
limilake --output=json --no-input lake file list finance --all
```

## limilake lake file ls

List files stored in a Lakehouse.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 100 | Page size (1–100). |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

Default: the first 100 files requested by the CLI. --page/--size select a server page; --all traverses server pages in batches of 100. Do not combine --all with --page or --size. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure.

 Deprecated spelling; use file list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake file ls finance
# Use without local prompts
limilake --no-input lake file ls finance --all
```

## limilake lake file put

Upload a local file into a Lakehouse.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--path` | false | — | Destination path within the Lakehouse files area. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `SOURCE` | true | — | Local file to upload. |

 Deprecated spelling; use file upload. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake file put finance report.csv
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input lake file put finance report.csv
```

## limilake lake file upload

Upload a local file into a Lakehouse.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--path` | false | — | Destination path within the Lakehouse files area. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |
| `SOURCE` | true | — | Local file to upload. |

 Deprecated spelling; use file upload. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake file upload finance report.csv
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input lake file upload finance report.csv
```

## limilake lake query

Run ad-hoc read-only SQL against one or more Lakehouses.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | true | — | Lakehouse ref to attach. Repeatable. |
| `--max-rows` | false | 1000 | Row cap. |
| `SQL` | true | — | SQL to execute (read-only). |

Use --result-schema v1 for positional columns/rows preserving duplicate column names, nulls, empty lists and exact numbers, with row_count/max_rows/limit_reached metadata. Legacy JSON/YAML keeps named row objects. Deprecated spelling; use query. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake query 'SELECT 1' --lakehouse=finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input lake query 'SELECT 1' --lakehouse=finance
```

## limilake lake query capture

Capture a named Query schema through authorized introspection.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | false | — | Lakehouse ref to attach. Repeatable; a sole linked Workspace Lakehouse is selected when omitted. |
| `--param` | false | — | Explicit parameter type as name=TYPE, such as limit=BIGINT or price=DECIMAL(10,2). Repeatable; overrides inference. |
| `--app` | false | — | App slug to add this Query capability to. Repeatable; a sole App is selected when omitted. |
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `SLUG` | true | — | Named Query slug to capture. |

 Deprecated spelling; use query capture. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake query capture example
# Use without local prompts
limilake --no-input lake query capture example
```

## limilake lake query test

Run a named Query with typed parameters and report its latency.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | false | — | Lakehouse ref to attach. Repeatable; a sole linked Workspace Lakehouse is selected when omitted. |
| `--param` | false | — | Parameter value as name=VALUE, typed by the reviewed schema. Repeatable. |
| `--repeat` | false | 1 | Number of runs to time (1-200). |
| `--max-rows` | false | 1000 | Row cap. |
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `SLUG` | true | — | Named Query slug to run. |

 Deprecated spelling; use query test. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake query test example
# Use without local prompts
limilake --no-input lake query test example
```

## limilake lake table

Discover and read tables inside Lakehouses.

Retained compatibility spelling.

The common flags above are inherited.

 Deprecated spelling; use table. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Inspect available actions
limilake lake table --help
# Inspect actions without local prompts
limilake --no-input lake table --help
```

## limilake lake table list

List discoverable tables inside Lakehouses you can read.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse` | false | — | Filter by an exact canonical Lakehouse slug, qualified ref, or UUID. |

One complete server discovery response for authorized tables. --lakehouse and --workspace filter that response client-side; this endpoint has no page selector.

--lakehouse filters the complete authorized discovery response by canonical slug, qualified ref, or UUID; combine --workspace to disambiguate. An unmatched filter returns an empty successful collection. Under the default legacy policy, Workspace environment/checkout defaults remain ignored without explicit --workspace. The linked policy uses those defaults; --all-workspaces selects aggregate discovery. Deprecated spelling; use table list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake table list --lakehouse=sales --workspace=finance
# Use without local prompts
limilake --output=json --no-input lake table list --lakehouse=sales --workspace=finance
```

## limilake lake table ls

List discoverable tables inside Lakehouses you can read.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse` | false | — | Filter by an exact canonical Lakehouse slug, qualified ref, or UUID. |

One complete server discovery response for authorized tables. --lakehouse and --workspace filter that response client-side; this endpoint has no page selector.

--lakehouse filters the complete authorized discovery response by canonical slug, qualified ref, or UUID; combine --workspace to disambiguate. An unmatched filter returns an empty successful collection. Under the default legacy policy, Workspace environment/checkout defaults remain ignored without explicit --workspace. The linked policy uses those defaults; --all-workspaces selects aggregate discovery. Deprecated spelling; use table list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake table ls --lakehouse=sales --workspace=finance
# Use without local prompts
limilake --no-input lake table ls --lakehouse=sales --workspace=finance
```

## limilake lake table read

Read rows from a table through the Lake Query API.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | true | — | Lakehouse ref the table lives in. |
| `--limit` | false | 100 | Max rows. |
| `TABLE` | true | — | Table as schema.table. |

Use --result-schema v1 for positional columns/rows preserving duplicate column names, nulls, empty lists and exact numbers, with row_count/max_rows/limit_reached metadata. Legacy JSON/YAML keeps named row objects. Deprecated spelling; use table read. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake lake table read public.customers --lakehouse=finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input lake table read public.customers --lakehouse=finance
```

## limilake lakehouse

Manage lakehouses (server-side data containers).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake lakehouse --help
# Inspect actions without local prompts
limilake --no-input lakehouse --help
```

## limilake lakehouse create

Create a lakehouse (defaults to bronze/silver/gold schemas).

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--description` | false | — | Optional description. |
| `NAME` | true | — | Lakehouse name. |

Examples:

```bash
# Example
limilake lakehouse create work
# Use without local prompts
limilake --no-input lakehouse create work
```

## limilake lakehouse delete

Delete a lakehouse after explicit confirmation.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Confirm deletion. |
| `--force` | false | false | Skip the confirmation prompt for this destructive operation. |
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

Examples:

```bash
# Example
limilake lakehouse delete finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input lakehouse delete finance --yes
```

## limilake lakehouse explain

Explain a lakehouse: live schema from the catalog + the concept doc.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

Examples:

```bash
# Example
limilake lakehouse explain finance
# Use without local prompts
limilake --no-input lakehouse explain finance
```

## limilake lakehouse list

List lakehouses (optionally scoped to one workspace).

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 50 | Page size (max 100). |

Default: one page selected by --page/--size. --all traverses every server page in batches of 100; do not combine it with --page or --size. A failed later page returns failure without printing a partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

Examples:

```bash
# Example
limilake lakehouse list
# Use without local prompts
limilake --output=json --no-input lakehouse list --all
```

## limilake lakehouse schema

List a lakehouse's schemas.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

Bounded schema result: the API request caps the returned collection; this command exposes no continuation.

 Use --grammar canonical to list and select the noun's explicit verbs. Default legacy arguments and actions remain unchanged during the migration window.

Examples:

```bash
# Example
limilake lakehouse schema finance
# Use without local prompts
limilake --no-input lakehouse schema finance
```

## limilake lakehouse schema show

Show a Lakehouse's schemas.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

 Select this noun/verb form with --grammar canonical. The default legacy syntax remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake --grammar=canonical lakehouse schema show finance
# Use without local prompts
limilake --grammar=canonical --output=json --no-input lakehouse schema show finance
```

## limilake lakehouse show

Show a lakehouse's details.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `LAKEHOUSE` | true | — | Lakehouse UUID, slug, or name. |

Examples:

```bash
# Example
limilake lakehouse show finance
# Use without local prompts
limilake --output=json --no-input lakehouse show finance
```

## limilake lineage

Show data lineage for a table.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake lineage --help
# Inspect actions without local prompts
limilake --no-input lineage --help
```

## limilake lineage show

Show upstream and downstream lineage for a table in the workspace.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `TABLE` | true | — | Table as schema.table, bare name, or node id. |

Examples:

```bash
# Example
limilake lineage show public.customers
# Use without local prompts
limilake --output=json --no-input lineage show public.customers
```

## limilake member

Manage workspace members (list/add/remove/transfer-owner).

The common flags above are inherited.

 Deprecated spelling; use workspace member. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Inspect available actions
limilake member --help
# Inspect actions without local prompts
limilake --no-input member --help
```

## limilake member add

Add a user to a workspace at the given access level.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--role` | false | member | Access level for the new member. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or name. |
| `USER` | true | — | User email or UUID to add. |

 Deprecated spelling; use workspace member add USER --workspace WORKSPACE --access-level LEVEL. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake member add finance alice@example.com
# Use without local prompts
limilake --no-input member add finance alice@example.com
```

## limilake member list

List the members of a workspace.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `WORKSPACE` | true | — | Workspace UUID, slug, or name. |

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

 Deprecated spelling; use workspace member list --workspace WORKSPACE. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake member list finance
# Use without local prompts
limilake --output=json --no-input member list finance
```

## limilake member remove

Remove a user from a workspace.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Skip the confirmation prompt. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or name. |
| `USER` | true | — | User email or UUID to remove. |

 Deprecated spelling; use workspace member remove USER --workspace WORKSPACE. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake member remove finance alice@example.com
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input member remove finance alice@example.com --yes
```

## limilake member transfer-owner

Promote an existing member to owner (additive ownership transfer).

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Skip the confirmation prompt. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or name. |
| `USER` | true | — | User email or UUID to promote to owner. |

 Deprecated spelling; use workspace member promote USER --workspace WORKSPACE. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake member transfer-owner finance alice@example.com
# Use without local prompts
limilake --no-input member transfer-owner finance alice@example.com --yes
```

## limilake profile

Manage named authenticated environments.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake profile --help
# Inspect actions without local prompts
limilake --no-input profile --help
```

## limilake profile delete

Delete a profile and all locally stored credential bundles belonging to it.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `NAME` | true | — | Profile to delete. |

Examples:

```bash
# Example
limilake profile delete work
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input profile delete work
```

## limilake profile list

List profiles without reading or revealing credential material.

The common flags above are inherited.

Complete local profile configuration; no API request or remote pagination.

Examples:

```bash
# Example
limilake profile list
# Use without local prompts
limilake --output=json --no-input profile list
```

## limilake profile show

Show one profile's non-secret, server-derived metadata.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `NAME` | false | — | Profile name; defaults to active. |

Examples:

```bash
# Example
limilake profile show work
# Use without local prompts
limilake --output=json --no-input profile show work
```

## limilake profile use

Select the process-default profile for future invocations.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `NAME` | true | — | Profile to make active. |

Examples:

```bash
# Example
limilake profile use work
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input profile use work
```

## limilake provider

Discover Connection providers (alias of connection provider).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake provider --help
# Inspect actions without local prompts
limilake --no-input provider --help
```

## limilake provider list

List catalog providers and their safe setup capabilities.

The common flags above are inherited.

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake provider list
# Use without local prompts
limilake --output=json --no-input provider list
```

## limilake provider show

Show the canonical Setup Contract for one provider.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `PROVIDER` | true | — | Catalog provider id. |

Provider IDs come from live discovery. An unambiguous nearby ID is suggested after not-found; the CLI never substitutes it or retries automatically.

Examples:

```bash
# Example
limilake provider show aws-s3
# Use without local prompts
limilake --output=json --no-input provider show aws-s3
```

## limilake publication

Inspect and reverse Publications.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake publication --help
# Inspect actions without local prompts
limilake --no-input publication --help
```

## limilake publication rollback

Reactivate a retained Deployment Manifest without running a Build.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--no-wait` | false | false | Report the recorded attempt's identity immediately instead of following it to a terminal state. |
| `MANIFEST` | true | — | Deployment Manifest UUID to reactivate, read from the deployment_manifest_id field of 'limilake publication show'. |

Examples:

```bash
# Example
limilake publication rollback 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input publication rollback 11111111-1111-4111-8111-111111111111
```

## limilake publication show

Show one Publish attempt, defaulting to this Workspace's newest.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `ATTEMPT` | false | — | Publish attempt UUID. Omit for this Workspace's newest attempt. |

Examples:

```bash
# Example
limilake publication show
# Use without local prompts
limilake --output=json --no-input publication show
```

## limilake query

Run ad-hoc read-only SQL against one or more Lakehouses.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | true | — | Lakehouse ref to attach. Repeatable. |
| `--max-rows` | false | 1000 | Row cap. |
| `SQL` | true | — | SQL to execute (read-only). |

Use --result-schema v1 for positional columns/rows preserving duplicate column names, nulls, empty lists and exact numbers, with row_count/max_rows/limit_reached metadata. Legacy JSON/YAML keeps named row objects.

Examples:

```bash
# Example
limilake query 'SELECT 1' --lakehouse=finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input query 'SELECT 1' --lakehouse=finance
```

## limilake query capture

Capture a named Query schema through authorized introspection.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | false | — | Lakehouse ref to attach. Repeatable; a sole linked Workspace Lakehouse is selected when omitted. |
| `--param` | false | — | Explicit parameter type as name=TYPE, such as limit=BIGINT or price=DECIMAL(10,2). Repeatable; overrides inference. |
| `--app` | false | — | App slug to add this Query capability to. Repeatable; a sole App is selected when omitted. |
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `SLUG` | true | — | Named Query slug to capture. |

Examples:

```bash
# Example
limilake query capture example
# Use without local prompts
limilake --no-input query capture example
```

## limilake query test

Run a named Query with typed parameters and report its latency.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | false | — | Lakehouse ref to attach. Repeatable; a sole linked Workspace Lakehouse is selected when omitted. |
| `--param` | false | — | Parameter value as name=VALUE, typed by the reviewed schema. Repeatable. |
| `--repeat` | false | 1 | Number of runs to time (1-200). |
| `--max-rows` | false | 1000 | Row cap. |
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `SLUG` | true | — | Named Query slug to run. |

Examples:

```bash
# Example
limilake query test example
# Use without local prompts
limilake --no-input query test example
```

## limilake report

Report platform friction to LimiLake support.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--body` | false | — | Optional Markdown details as literal text, @file, or - for standard input. |
| `SUBJECT` | true | — | Short description of what is not working. |

Examples:

```bash
# Example
limilake report 'A Workspace query failed'
# Use without local prompts
limilake --no-input report 'A Workspace query failed'
```

## limilake role

Manage roles (list/assign/revoke).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake role --help
# Inspect actions without local prompts
limilake --no-input role --help
```

## limilake role assign

Assign a user to a role.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `ROLE` | true | — | Role UUID or exact name. |
| `USER` | true | — | User UUID to add to the role. |

Examples:

```bash
# Example
limilake role assign member 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input role assign member 11111111-1111-4111-8111-111111111111
```

## limilake role list

List roles defined in the tenant.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 50 | Page size (max 100). |

Default: one page selected by --page/--size. --all traverses every server page in batches of 100; do not combine it with --page or --size. A failed later page returns failure without printing a partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

Examples:

```bash
# Example
limilake role list
# Use without local prompts
limilake --output=json --no-input role list --all
```

## limilake role revoke

Revoke a user from a role.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Skip the confirmation prompt. |
| `ROLE` | true | — | Role UUID or exact name. |
| `USER` | true | — | User UUID to remove from the role. |

Examples:

```bash
# Example
limilake role revoke member 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input role revoke member 11111111-1111-4111-8111-111111111111 --yes
```

## limilake run

Inspect execution history.

Retained compatibility spelling.

The common flags above are inherited.

 Deprecated spelling; use execution. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Inspect available actions
limilake run --help
# Inspect actions without local prompts
limilake --no-input run --help
```

## limilake run cancel

Cancel a live execution and its linked sandbox.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution cancel. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake run cancel 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input run cancel 11111111-1111-4111-8111-111111111111
```

## limilake run list

List recent executions.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 50 | Page size. |

Default: one page selected by --page/--size. --all traverses every server page in batches of 100; do not combine it with --page or --size. A failed later page returns failure without printing a partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

 Deprecated spelling; use execution list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake run list
# Use without local prompts
limilake --output=json --no-input run list --all
```

## limilake run logs

Show an execution's captured log lines.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--limit` | false | 200 | Maximum log lines per page. |
| `EXECUTION_ID` | true | — | Execution UUID. |

All log pages are read using the server's next offset. --limit is the per-page size.

 Deprecated spelling; use execution logs. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake run logs 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input run logs 11111111-1111-4111-8111-111111111111
```

## limilake run show

Show one execution's details.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution show. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake run show 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --output=json --no-input run show 11111111-1111-4111-8111-111111111111
```

## limilake run view

Deprecated spelling of show; retained during migration.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution show. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake run view 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input run view 11111111-1111-4111-8111-111111111111
```

## limilake run watch

Poll an execution until terminal.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `EXECUTION_ID` | true | — | Execution UUID. |

 Deprecated spelling; use execution watch. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake run watch 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input run watch 11111111-1111-4111-8111-111111111111
```

## limilake runtime

Execute Functions through the retained compatibility route.

Retained compatibility spelling.

The common flags above are inherited.

 Deprecated spelling; use function. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Inspect available actions
limilake runtime --help
# Inspect actions without local prompts
limilake --no-input runtime --help
```

## limilake runtime invoke

Invoke a Function server-side or in the local Workspace runtime.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--input` | false | — | JSON object as run input or HTTP body; pass - to read stdin. |
| `--local` | false | false | Run in the Workspace runtime instead of the live sandbox. |
| `--branch` | false | main | Git branch for action or sync dispatch. |
| `--handler` | false | — | Deliberate handler to run: action or sync. Required when the Function declares both. |
| `--path` | false | — | HTTP Function route; inferred for a single-route Function. |
| `--method` | false | — | HTTP Function method; inferred for a single-route Function. |
| `--query` | false | — | HTTP query key=value; repeatable. |
| `FUNCTION` | true | — | Function name or item-id (ULID). |

 Deprecated spelling; use function invoke. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake runtime invoke recalculate-invoice
# Use without local prompts
limilake --no-input runtime invoke recalculate-invoice
```

## limilake runtime serve

Serve Functions through the Workspace-pinned runtime.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--schedules` | false | false | Also run scheduled triggers locally. |
| `PATH` | false | — | Function file or directory; defaults to the whole Workspace. |

This long-running or streamed command retains its own output protocol. Record output flags do not turn child or streamed output into a single JSON document. Deprecated spelling; use function serve. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake runtime serve
# Use without local prompts
limilake --no-input runtime serve
```

## limilake runtime trigger

Simulate Function triggers.

Retained compatibility spelling.

The common flags above are inherited.

 Deprecated spelling; use function trigger. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Inspect available actions
limilake runtime trigger --help
# Inspect actions without local prompts
limilake --no-input runtime trigger --help
```

## limilake runtime trigger fire

Enqueue a schedule-attributed Function Run.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--input` | false | — | JSON object as run input; pass - to read stdin. |
| `--branch` | false | main | Git branch to dispatch. |
| `--handler` | false | — | Deliberate handler to run: action or sync. Required when the Function declares both. |
| `FUNCTION` | true | — | Function name or item-id (ULID). |

 Deprecated spelling; use function trigger fire. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake runtime trigger fire recalculate-invoice
# Use without local prompts
limilake --no-input runtime trigger fire recalculate-invoice
```

## limilake sandbox

Operate live Sandbox Sessions.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake sandbox --help
# Inspect actions without local prompts
limilake --no-input sandbox --help
```

## limilake sandbox cancel

Cancel a live Sandbox Session.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `SANDBOX_ID` | true | — | Sandbox Session UUID. |

Examples:

```bash
# Example
limilake sandbox cancel 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input sandbox cancel 11111111-1111-4111-8111-111111111111
```

## limilake secret

Manage workspace secrets (reveal-only key/value credential material).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake secret --help
# Inspect actions without local prompts
limilake --no-input secret --help
```

## limilake secret create

Create a reveal-only secret from private JSON input or field pairs.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--field` | false | — | Field as KEY=VALUE (repeatable); prefer --values-from for secrets. |
| `--values-policy` | false | legacy | Input validation policy; strict rejects duplicate and overlapping values. |
| `--values-from` | false | — | Read a JSON object of strings from standard input (-) or a private @file; maximum 1 MiB. |
| `NAME` | false | — | Secret display name; auto-named server-side if omitted. |

Supply a bounded JSON object through --values-from - (stdin) or --values-from @private-file. Keep secrets out of argv; legacy --field remains available. Use --values-policy strict to reject overlapping sources and duplicate keys before mutation; default legacy preserves retained decoding and last-value precedence throughout the documented compatibility window. --workspace or its environment fallback remains required, and --no-input permits explicitly requested stdin data.

Examples:

```bash
# Example
limilake secret create service-key --values-from=- --values-policy=strict --workspace=finance < private-secret.json
# Use without local prompts
limilake --no-input secret create service-key --values-from=- --values-policy=strict --workspace=finance < private-secret.json
```

## limilake secret delete

Delete a secret from a workspace.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes, -y` | false | false | Skip the confirmation prompt. |
| `SECRET_ID` | true | — | Secret id (UUID). |

A supplied --workspace is required; the Workspace environment fallback is also accepted. Omitting both does not select the linked checkout.

Examples:

```bash
# Example
limilake secret delete 11111111-1111-4111-8111-111111111111 --workspace=finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input secret delete 11111111-1111-4111-8111-111111111111 --workspace=finance --yes
```

## limilake secret list

List secrets for a workspace, or across every workspace when omitted.

The common flags above are inherited.

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake secret list
# Use without local prompts
limilake --output=json --no-input secret list
```

## limilake secret rename

Rename a secret's display label (unique in the workspace).

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `SECRET_ID` | true | — | Secret id (UUID). |
| `NEW_NAME` | true | — | New secret name (workspace-unique). |

A supplied --workspace is required; the Workspace environment fallback is also accepted. Omitting both does not select the linked checkout.

Examples:

```bash
# Example
limilake secret rename 11111111-1111-4111-8111-111111111111 'Updated label' --workspace=finance
# Use without local prompts
limilake --no-input secret rename 11111111-1111-4111-8111-111111111111 'Updated label' --workspace=finance
```

## limilake shortcut

Manage cross-workspace shortcut grants (list/add/remove).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake shortcut --help
# Inspect actions without local prompts
limilake --no-input shortcut --help
```

## limilake shortcut add

Create a cross-workspace delegation grant into the consuming lakehouse.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--source-lakehouse` | true | — | Source Lakehouse UUID, slug, or name. |
| `--source-schema` | true | — | Source schema name. |
| `--source-table` | true | — | Source table name (named tables only). |
| `--alias` | true | — | Consumer-side alias (unique per consuming Lakehouse). |
| `--source-workspace` | false | — | Workspace to scope the source Lakehouse lookup. |
| `LAKEHOUSE` | true | — | Consuming Lakehouse UUID, slug, or name. |

Examples:

```bash
# Example
limilake shortcut add finance --source-lakehouse=sales --source-schema=public --source-table=customers --alias=sales_customers
# Use without local prompts
limilake --no-input shortcut add finance --source-lakehouse=sales --source-schema=public --source-table=customers --alias=sales_customers
```

## limilake shortcut list

List the shortcut grants in a consuming lakehouse.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `LAKEHOUSE` | true | — | Consuming Lakehouse UUID, slug, or name. |

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake shortcut list finance
# Use without local prompts
limilake --output=json --no-input shortcut list finance
```

## limilake shortcut remove

Revoke a shortcut grant from a consuming lakehouse.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `LAKEHOUSE` | true | — | Consuming Lakehouse UUID, slug, or name. |
| `GRANT_ID` | true | — | Shortcut Grant UUID to revoke. |

Examples:

```bash
# Example
limilake shortcut remove finance 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input shortcut remove finance 11111111-1111-4111-8111-111111111111
```

## limilake sql

Run ad-hoc read-only SQL against one or more Lakehouses.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | true | — | Lakehouse ref to attach. Repeatable. |
| `--max-rows` | false | 1000 | Row cap. |
| `SQL` | true | — | SQL to execute (read-only). |

Use --result-schema v1 for positional columns/rows preserving duplicate column names, nulls, empty lists and exact numbers, with row_count/max_rows/limit_reached metadata. Legacy JSON/YAML keeps named row objects. Deprecated spelling; use query. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake sql 'SELECT 1' --lakehouse=finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input sql 'SELECT 1' --lakehouse=finance
```

## limilake sql capture

Capture a named Query schema through authorized introspection.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | false | — | Lakehouse ref to attach. Repeatable; a sole linked Workspace Lakehouse is selected when omitted. |
| `--param` | false | — | Explicit parameter type as name=TYPE, such as limit=BIGINT or price=DECIMAL(10,2). Repeatable; overrides inference. |
| `--app` | false | — | App slug to add this Query capability to. Repeatable; a sole App is selected when omitted. |
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `SLUG` | true | — | Named Query slug to capture. |

Examples:

```bash
# Example
limilake sql capture example
# Use without local prompts
limilake --no-input sql capture example
```

## limilake sql test

Run a named Query with typed parameters and report its latency.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | false | — | Lakehouse ref to attach. Repeatable; a sole linked Workspace Lakehouse is selected when omitted. |
| `--param` | false | — | Parameter value as name=VALUE, typed by the reviewed schema. Repeatable. |
| `--repeat` | false | 1 | Number of runs to time (1-200). |
| `--max-rows` | false | 1000 | Row cap. |
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `SLUG` | true | — | Named Query slug to run. |

Examples:

```bash
# Example
limilake sql test example
# Use without local prompts
limilake --no-input sql test example
```

## limilake table

Discover and read tables inside Lakehouses.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake table --help
# Inspect actions without local prompts
limilake --no-input table --help
```

## limilake table list

List discoverable tables inside Lakehouses you can read.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse` | false | — | Filter by an exact canonical Lakehouse slug, qualified ref, or UUID. |

One complete server discovery response for authorized tables. --lakehouse and --workspace filter that response client-side; this endpoint has no page selector.

--lakehouse filters the complete authorized discovery response by canonical slug, qualified ref, or UUID; combine --workspace to disambiguate. An unmatched filter returns an empty successful collection. Under the default legacy policy, Workspace environment/checkout defaults remain ignored without explicit --workspace. The linked policy uses those defaults; --all-workspaces selects aggregate discovery.

Examples:

```bash
# Example
limilake table list --lakehouse=sales --workspace=finance
# Use without local prompts
limilake --output=json --no-input table list --lakehouse=sales --workspace=finance
```

## limilake table ls

List discoverable tables inside Lakehouses you can read.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse` | false | — | Filter by an exact canonical Lakehouse slug, qualified ref, or UUID. |

One complete server discovery response for authorized tables. --lakehouse and --workspace filter that response client-side; this endpoint has no page selector.

--lakehouse filters the complete authorized discovery response by canonical slug, qualified ref, or UUID; combine --workspace to disambiguate. An unmatched filter returns an empty successful collection. Under the default legacy policy, Workspace environment/checkout defaults remain ignored without explicit --workspace. The linked policy uses those defaults; --all-workspaces selects aggregate discovery. Deprecated spelling; use table list. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake table ls --lakehouse=sales --workspace=finance
# Use without local prompts
limilake --no-input table ls --lakehouse=sales --workspace=finance
```

## limilake table read

Read rows from a table through the Lake Query API.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--lakehouse, -l` | true | — | Lakehouse ref the table lives in. |
| `--limit` | false | 100 | Max rows. |
| `TABLE` | true | — | Table as schema.table. |

Use --result-schema v1 for positional columns/rows preserving duplicate column names, nulls, empty lists and exact numbers, with row_count/max_rows/limit_reached metadata. Legacy JSON/YAML keeps named row objects.

Examples:

```bash
# Example
limilake table read public.customers --lakehouse=finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input table read public.customers --lakehouse=finance
```

## limilake tenant

Inspect and select verified Tenant authority.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake tenant --help
# Inspect actions without local prompts
limilake --no-input tenant --help
```

## limilake tenant current

Show the canonical Tenant bound to the selected profile.

The common flags above are inherited.

Examples:

```bash
# Example
limilake tenant current
# Use without local prompts
limilake --no-input tenant current
```

## limilake tenant list

List live Tenant memberships for the selected authenticated profile.

The common flags above are inherited.

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake tenant list
# Use without local prompts
limilake --output=json --no-input tenant list
```

## limilake tenant use

Switch an OAuth profile through the server's live-membership policy.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `TARGET` | true | — | Target Tenant UUID or slug. |

Examples:

```bash
# Example
limilake tenant use acme
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input tenant use acme
```

## limilake toolchain

Inspect and repair the managed Build toolchain cache.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake toolchain --help
# Inspect actions without local prompts
limilake --no-input toolchain --help
```

## limilake toolchain doctor

Verify the exact managed Build toolchain cache without network access or disk mutation.

The common flags above are inherited.

Examples:

```bash
# Example
limilake toolchain doctor
# Use without local prompts
limilake --no-input toolchain doctor
```

## limilake toolchain repair

Atomically restore the exact managed Build toolchain from signed release artifacts.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--offline` | false | false | Use only an already valid exact-version cache; never contact the package origin. |

Examples:

```bash
# Example
limilake toolchain repair
# Use without local prompts
limilake --no-input toolchain repair
```

## limilake update

Explicitly update the standalone CLI from signed release metadata.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--channel` | false | — | Resolve the current version from this release channel. |
| `--version` | false | — | Select an exact signed release version. |

upgrade and update use the same signed-manifest verification and atomic replacement. --version selects an exact signed release. The version check reports executable/PATH shadowing and observed uv launchers with migration commands; it makes no repairs.

Examples:

```bash
# Example
limilake update --channel=stable
# Use without local prompts
limilake --no-input update --channel=stable
```

## limilake upgrade

Explicitly update the standalone CLI from signed release metadata.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--channel` | false | — | Resolve the current version from this release channel. |
| `--version` | false | — | Select an exact signed release version. |

upgrade and update use the same signed-manifest verification and atomic replacement. --version selects an exact signed release. The version check reports executable/PATH shadowing and observed uv launchers with migration commands; it makes no repairs.

Examples:

```bash
# Example
limilake upgrade --channel=stable
# Use without local prompts
limilake --no-input upgrade --channel=stable
```

## limilake user

Manage tenant users (list/invite/remove).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake user --help
# Inspect actions without local prompts
limilake --no-input user --help
```

## limilake user deactivate

Deactivate a user's Tenant access.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Skip the confirmation prompt. |
| `USER_ID` | true | — | User UUID to deactivate. |

Examples:

```bash
# Example
limilake user deactivate 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --no-input user deactivate 11111111-1111-4111-8111-111111111111 --yes
```

## limilake user invite

Add a user to the current tenant.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--password` | false | — | Initial password. Prompted (hidden) when omitted. |
| `--first-name` | false | — | User's first name. |
| `--last-name` | false | — | User's last name. |
| `EMAIL` | true | — | Email address of the user to add. |

This retained user-provisioning operation is not an invitation flow. Onboarding stays interactive: each person signs in themselves. The examples inspect this command without executing it, then show recipient sign-in and status. They never create credentials for someone else.

Examples:

```bash
# Inspect the retained provisioning options
limilake user invite alice@example.com --first-name=Alice --help
# Inspect options without prompts
limilake --no-input user invite alice@example.com --help
# The recipient signs in interactively
limilake auth login --host=app.limilake.com --profile=work
# Inspect the caller's own sign-in
limilake --no-input --output=json auth status
```

## limilake user list

List users in the current tenant.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--search` | false | — | Filter users by email or name. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 50 | Page size (max 100). |

Default: one page selected by --page/--size. --all traverses every server page in batches of 100; do not combine it with --page or --size. A failed later page returns failure without printing a partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

Examples:

```bash
# Example
limilake user list
# Use without local prompts
limilake --output=json --no-input user list --all
```

## limilake user remove

Deprecated spelling of deactivate; retained during migration.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Skip the confirmation prompt. |
| `USER_ID` | true | — | User UUID to deactivate. |

 Deprecated spelling; use user deactivate. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake user remove 11111111-1111-4111-8111-111111111111
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input user remove 11111111-1111-4111-8111-111111111111 --yes
```

## limilake version

Report the executable release and source identity.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--check` | false | false | Compare the installed CLI with verified stable release metadata (5s maximum). |

Use --version --check or version --check for an explicit five-second signed stable-release comparison and the exact upgrade command. Ordinary version output is offline. An available upgrade exits 0; a failed explicit check exits 6. A platform absent from the signed manifest reports unsupported_platform with upgrade_available:false and an empty upgrade_command.

Examples:

```bash
# Example
limilake version --check
# Use without local prompts
limilake --output=json --no-input version --check
```

## limilake workspace

Manage Workspaces (access-control boundaries).

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake workspace --help
# Inspect actions without local prompts
limilake --no-input workspace --help
```

## limilake workspace clone

Clone a Workspace repository and link the checkout in one step.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--link, --no-link` | false | true | Link the checkout after cloning (default); use --no-link to skip binding. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or display name. |
| `DIRECTORY` | false | — | Directory to clone into. Defaults to the Workspace repository name. |

Clone uses ordinary Git. Absolute destinations work independently of an unavailable current directory; relative paths require a readable current directory and a readable ancestor walk, failing before mutation otherwise. No existing checkout is required. Malformed bindings exit 2 with checkout context; cwd and binding permission failures exit 5 with preserved causes. Destination shapes are checked before binding reads. Default --link binds the checkout; --no-link keeps a new clone's Git credential helper and allows workspace link later. Last --link/--no-link wins. Git creates missing parent directories; dangling, looping, or non-directory parents fail with a path-specific usage error (exit 2) before Git starts; unreadable destinations or parents report permission denied (exit 5). Inspection errors preserve their filesystem cause. Matching reruns compare checkout-root directory identity, so a symlinked parent may use a different path spelling, and reuse the repository without changing Git configuration; unconfirmed root identity is refused without assuming why comparison failed. Link failure preserves the clone and reports the recovery command. Git owns fetch, pull, branches, and push.

Examples:

```bash
# Clone and link the Workspace
limilake workspace clone finance ./finance
# Clone to an absolute destination without linking
limilake --no-input --output=json workspace clone finance /tmp/finance-checkout --no-link
```

## limilake workspace create

Create a new Workspace.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--description` | false | — | Optional description. |
| `--idempotency-key` | false | — | Stable caller key for safely reconnecting to the same create request. |
| `DISPLAY_NAME` | true | — | Human-friendly Workspace label. |

Examples:

```bash
# Example
limilake workspace create Finance
# Use without local prompts
limilake --no-input workspace create Finance
```

## limilake workspace delete

Delete a Workspace after explicit confirmation.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Skip the confirmation prompt. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or display name. |

Examples:

```bash
# Example
limilake workspace delete finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input workspace delete finance --yes
```

## limilake workspace doctor

Explain whether ordinary Git can safely use the linked Workspace remote.

The common flags above are inherited.

Examples:

```bash
# Example
limilake workspace doctor
# Use without local prompts
limilake --no-input workspace doctor
```

## limilake workspace git-credential

Emit credentials through Git's credential-helper protocol.

Retained compatibility spelling.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `ACTION` | true | — | Git credential action. |

This hidden route speaks Git's credential-helper protocol. Ordinary users run auth setup-git; do not interpret helper output as a CLI record.

Examples:

```bash
# Configure ordinary Git authentication
limilake auth setup-git
# Inspect the helper protocol options
limilake workspace git-credential --help
```

## limilake workspace init

Lay the Workspace Contract skeleton into this checkout.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--directory` | false | — | Directory to initialize. Defaults to the current directory. |
| `--dry-run` | false | false | Report what would change without writing anything. |

Examples:

```bash
# Example
limilake workspace init
# Use without local prompts
limilake --no-input workspace init
```

## limilake workspace link

Bind the current checkout to a Workspace without wrapping Git.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `WORKSPACE` | true | — | Workspace UUID, slug, or display name. |

Examples:

```bash
# Example
limilake workspace link finance
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input workspace link finance
```

## limilake workspace list

List Workspaces you belong to.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--all` | false | false | Read every server page; do not combine with --page or --size. |
| `--page` | false | 1 | Page number. |
| `--size` | false | 50 | Page size. |

Default: one page selected by --page/--size. --all traverses every server page in batches of 100; do not combine it with --page or --size. A failed later page returns failure without printing a partial collection. All traversals stop at 10000 records or 1000 requests and emit no partial collection on failure. Listings are not transactional snapshots.

Examples:

```bash
# Example
limilake workspace list
# Use without local prompts
limilake --output=json --no-input workspace list --all
```

## limilake workspace member

Manage Workspace membership and access levels.

The common flags above are inherited.

Examples:

```bash
# Inspect available actions
limilake workspace member --help
# Inspect actions without local prompts
limilake --no-input workspace member --help
```

## limilake workspace member add

Add a user at the selected Workspace access level.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--access-level` | false | member | Workspace access level. |
| `--role` | false | — | Deprecated alias of --access-level. |
| `USER` | true | — | User email or UUID to add. |

Examples:

```bash
# Example
limilake workspace member add alice@example.com --workspace=finance
# Use without local prompts
limilake --no-input workspace member add alice@example.com --workspace=finance
```

## limilake workspace member list

List members of the selected Workspace.

The common flags above are inherited.

One API collection with no additional CLI paging options. Its API-defined scope and limits still apply.

Examples:

```bash
# Example
limilake workspace member list --workspace=finance
# Use without local prompts
limilake --output=json --no-input workspace member list --workspace=finance
```

## limilake workspace member promote

Add owner access to an existing member; existing owners remain owners.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Skip the confirmation prompt. |
| `USER` | true | — | Existing member's email or UUID. |

Examples:

```bash
# Example
limilake workspace member promote alice@example.com --workspace=finance
# Use without local prompts
limilake --no-input workspace member promote alice@example.com --workspace=finance --yes
```

## limilake workspace member remove

Remove a user's Workspace membership.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--yes` | false | false | Skip the confirmation prompt. |
| `USER` | true | — | User email or UUID to remove. |

Examples:

```bash
# Example
limilake workspace member remove alice@example.com --workspace=finance
# Use without local prompts
limilake --no-input workspace member remove alice@example.com --workspace=finance --yes
```

## limilake workspace migrate

Upgrade initialized Workspace source to the current Contract without pushing or publishing; use workspace init when limilake.toml is missing.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--directory` | false | — | Directory to start Workspace root discovery from. Defaults to the current directory. |
| `--dry-run` | false | false | Report the Contract migration without writing anything. |

Examples:

```bash
# Example
limilake workspace migrate
# Use without local prompts
limilake --no-input workspace migrate
```

## limilake workspace settings

Deprecated spelling of update; retained during migration.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--display-name` | false | — | New display name. |
| `--description` | false | — | New description. |
| `--icon` | false | — | New curated Lucide icon name. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or display name. |

 Deprecated spelling; use workspace update. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake workspace settings finance --display-name=Finance
# Use without local prompts
limilake --no-input workspace settings finance --display-name=Finance
```

## limilake workspace show

Show a single Workspace.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `WORKSPACE` | true | — | Workspace UUID, slug, or display name. |

Examples:

```bash
# Example
limilake workspace show finance
# Use without local prompts
limilake --output=json --no-input workspace show finance
```

## limilake workspace status

Show the selected profile and local Workspace checkout binding.

The common flags above are inherited.

With --result-schema v1 and JSON/YAML output, outside/unlinked status succeeds with nullable checkout/workspace, linked:false, profile and recovery; auth and inspection failures still fail. Linked details retain the existing diagnostics. Table output and default/explicit legacy retain exit 4 outside/unlinked through the compatibility window.

Examples:

```bash
# Example
limilake workspace status
# Use without local prompts
limilake --result-schema=v1 --output=json --no-input workspace status
```

## limilake workspace update

Update a Workspace's editable settings.

The common flags above are inherited.

| Parameter | Required | Default | Purpose |
|---|---|---|---|
| `--display-name` | false | — | New display name. |
| `--description` | false | — | New description. |
| `--icon` | false | — | New curated Lucide icon name. |
| `WORKSPACE` | true | — | Workspace UUID, slug, or display name. |

Examples:

```bash
# Example
limilake workspace update finance
# Use without local prompts
limilake --no-input workspace update finance
```

## limilake workspace whoami

Show the current authenticated principal and Tenant.

The common flags above are inherited.

 Deprecated spelling; use context. Legacy remains available for two subsequent stable releases and at least 30 days; removal requires an announced breaking release.

Examples:

```bash
# Example
limilake workspace whoami
# Use without local prompts
limilake --no-input workspace whoami
```

---

<!-- connections.md -->

---
title: Connections
slug: connections
summary: Reaching external providers from function code without raw secrets.
---

# Connections

A **Connection** is a reusable routing and authentication handle granted to a workspace. Its credential values are stored separately in the encrypted credential vault. Function code and the CLI reach the provider through the egress gateway, which enforces the Connection definition and injects credentials server-side. The raw credential is never handed to the caller.

## In function code

```python
from limilake import connections

# GET/POST/request/paginate proxy through the egress gateway.
resp = connections.get("stripe", "/v1/charges", params={"limit": 10})
data = resp.json()

# paginate() follows the provider's paging for you.
for page in connections.paginate("stripe", "/v1/customers"):
    ...
```

The ref you pass is the connection's **slug** (shown by `list_connections` and in the UI). It is matched against the grants your workspace holds, and the credential is injected at the gateway on each call. OAuth connections are refreshed at the gateway automatically.

## Revealing material

Connections are call-through only: the gateway injects the credential and your code never holds it. To read raw credential material directly instead (a database password, a raw API key, anything non-HTTP), use a **Secret** and `secrets.reveal("ref")`, which returns the material — gated, and only for revealable refs. A connection that explicitly opted into reveal can also be read this way.

Create a Secret from private JSON input, supplying the Workspace explicitly:

```bash
limilake secret create partner-db --workspace finance --values-from - --values-policy strict \
  --no-input < private-secret.json
limilake secret create partner-db --workspace finance \
  --values-from @private-secret.json --values-policy strict
```

The file contains one JSON object of string values, for example password and
username fields. Creation returns only field keys; the CLI has no reveal verb.

## Discover setup requirements

The server owns one Setup Contract for every catalog provider and Custom
Connection authentication profile. The portal, CLI, managed Agent, and external
automation consume the same stable requirement keys and validation rules.

```bash
limilake connection provider list
limilake connection provider show stripe
limilake --output json connection provider show stripe
```

The contract describes required fields, secret classification, choices,
recommended and known OAuth scopes, possible next actions, and safe
capabilities. It never contains submitted or stored values.

Provider IDs use the catalog's exact spelling, for example `aws-s3`. A misspelled
ID on `connection provider show` suggests a close live catalog ID
when unambiguous, while retaining failure. The CLI never substitutes or retries
the suggested provider automatically.

## Create a Connection

An interactive human can submit known non-sensitive values and let the CLI hide
any missing secret prompt:

```bash
limilake connection create --provider wint --workspace finance \
  --field username=11810
```

Direct values remain supported, but command-line arguments may be retained in
shell history or visible in process listings. Prefer structured standard input
or a protected file for secrets:

```bash
printf '%s' '{"username":"11810","password":"..."}' | \
  limilake --output json connection create \
    --provider wint --workspace finance --values-from -
```

Both `connection create` and `secret create` accept `--values-from -` or `@file`,
bounded to 1 MiB. Add `--values-policy strict` to require one UTF-8 JSON object of
strings with unique, non-blank keys and no surrounding key whitespace. Nulls,
arrays, numbers, duplicate keys, extra JSON documents and keys overlapping
`--field` fail before mutation. Distinct fields combine. Errors never echo
values. File errors name the quoted path and safe failure reason.

The default `--values-policy legacy` preserves the existing Connection JSON
decoder and last-value precedence, including repeated `--field KEY=VALUE`.
Inputs relying on that behavior receive a value-free stderr deprecation.
Legacy remains available for two subsequent stable releases and at least 30 days
from its deprecation; removal requires an announced breaking release.
Prefer strict mode for new scripts. Stdin or a private file keeps secret values
out of process arguments. `--no-input` suppresses prompts and still permits
explicitly requested stdin.

This is also the external-Agent flow: inspect the JSON contract, ask the human
only for missing requirements, submit values through standard input, and retain
the returned stable Connection ref. Agents are not required to author provider
YAML.

Initial OAuth begins with the same `create` command. The CLI opens the browser
unless `--no-browser` is set, then waits for the server-owned callback:

```bash
limilake connection create --provider fortnox --workspace finance \
  --scope invoice --scope supplier --timeout 5m

limilake connection create --provider fortnox --workspace finance \
  --no-browser --timeout 10m
```

Known scopes are recommendations, not a hard allowlist. Sanitized custom scope
strings can be requested; the upstream provider makes the final decision.
Replace a revoked grant or request changed scopes without changing the stable
Connection ref:

```bash
limilake connection reauthorize fortnox --workspace finance \
  --scope invoice --scope custom.scope
```

Create a bounded Custom Connection without a YAML specification:

```bash
printf '%s' '{"api_key":"..."}' | \
  limilake connection create --custom --name partner-api --workspace finance \
    --base-url https://api.partner.example/v1 \
    --allowed-host api.partner.example \
    --auth-method api_key --inject-header X-API-Key \
    --values-from -
```

Custom routing still passes server validation: HTTPS only, explicit safe hosts,
reviewed authentication profiles, and declarative header/query injection. Raw
reveal-only material belongs under `limilake secret`, not a Custom Connection.

## Rotate static credentials or update routing

Rotate an S3 secret in place by piping one JSON object into the update command:

```bash
limilake connection update enreach_s3 --workspace finance --values-from - \
  < private-rotation.json
```

The JSON object contains only the fields being changed, such as
`secret_access_key`. Keep secret values out of shell arguments and history.
These update verbs accept stdin only; `--values-from @file` is refused.
For a catalog Zendesk Connection using Basic authentication,
`limilake connection update helpdesk --field subdomain=acme-support` updates
Setup Contract-declared non-secret metadata.
Plain vault types do not classify secret fields; all their config keys, including
region/host, require stdin values. Display names use `--name`.

Update a custom API endpoint and replace its complete allowed-host set:

```bash
limilake connection update partner-api --workspace finance \
  --base-url https://api.partner.example/v2 \
  --allowed-host api.partner.example --inject-header X-API-Key
limilake credential update storage --name 'Finance storage'
```

Omitted fields remain unchanged. Catalog-owned routing cannot be overridden.
Connection updates need a linked or selected Workspace; direct Credential
updates use Tenant scope on legacy omission. Select a Workspace with
`--workspace`, its environment fallback, or `--workspace-policy linked` to use the
checkout. Conflicting Workspace environment defaults require an explicit
`--workspace`. Shared updates may affect several Workspace grants.
The result reports `affected_grants`. Both preserve the credential ID and every
stable Workspace ref and grant. OAuth credentials continue to use `reauthorize`.

Concurrent changes are rejected with retry advice; the CLI never repeats a secret
write automatically. JSON/YAML results contain only identity, display name,
revision and grant scope. Successful deletion releases the Workspace ref, so
recreation with the same explicit `--ref` works without choosing another name.

## Inspect, test, call, and delete

```bash
limilake connection list
limilake connection show stripe
limilake connection test stripe
limilake connection call stripe --method GET --path /v1/charges \
  --query limit=10
limilake connection call stripe --method POST --path /v1/refunds \
  --input @refund.json --output-file response.json
limilake connection delete stripe --yes
```

Keep query strings out of `--path`. Supply each decoded key/value through a
separate `--query`; the CLI encodes it for transport. Quote shell metacharacters:

```bash
limilake connection call graph --method GET --path /users \
  --query '$top=1' --query '$select=id,displayName'
```

A full `--path '/users?$top=1'` returns a recovery example. Remove any `#fragment`;
fragments are never sent to a provider. Error hints omit the supplied query and
fragment values.

`show` includes the definition, Setup Contract, lifecycle state, next action,
safe capabilities, and granted OAuth scopes. `test` performs one read-only GET.
`call` requires an explicit method and upstream-relative path; absolute URLs,
credential headers, and oversized input/output are rejected. For each call the
CLI exchanges its profile credential for a five-minute token bound to the
verified tenant user, identity, and one workspace. That token is never printed
or persisted. The egress gateway remains the enforcement and audit boundary for
SSRF, credential injection, rate limits, and the selected Connection ref.

## Why no raw secrets in the sandbox

The sandbox or short-lived CLI call token carries authority, not provider
credentials. Injecting credentials server-side, per call, keeps secret material
off untrusted machines and out of execution logs—the same boundary applies in a
live sandbox, local function runtime, and external CLI.


## Test authentication

```bash
limilake connection test enreach_s3 --workspace finance --probe provider --bucket finance-data
limilake connection test graph --workspace finance --probe provider --output json
limilake connection call graph --workspace finance --method GET --path /v1.0/me --fail
```

Provider mode sends bounded, read-only requests through the normal Connection
authorization path. S3 lists at most one object in the specified bucket. Graph
checks metadata for connectivity, then a read compatible with the stored
permission hints. Metadata alone does not verify authentication. A Connection
is `connected: true` only after a fresh successful authenticated request.

The report includes configuration, nullable `auth_verified` and `healthy` values,
probe HTTP statuses, timings, and remedies. It omits provider response bodies and
credentials. Unsupported providers or permission sets remain unknown. The
30-second default budget includes discovery, token acquisition, and all probes;
use `--timeout` to select another budget. Exit 0 means healthy, 1 means a failed
probe, 2 means missing bucket input, and 9 means authentication health is unknown.
Authority or discovery failures keep their normal error codes.

Omission and `--probe legacy` retain the previous `GET /` response and HTTP exit
behavior, with a deprecation notice. From the first stable release containing
authenticated provider probes they remain available for two subsequent stable
releases and at least 30 days; removal requires an announced
breaking release. `connection call --fail` opts into exit 1 for non-2xx responses
while retaining the response content. Without it, HTTP failures still exit 0.

---

<!-- functions.md -->

---
title: Functions
slug: functions
summary: Code-first .py items that expose actions, HTTP routes, sync, and schedules.
---

# Functions

A **function** lives at `functions/<slug>/function.py` in a Workspace. Its capabilities are inferred statically from the source — there are no `.limilake/` sidecar files. A function can expose:

- an **action** (`@fn.action`) — a callable operation,
- **HTTP routes** — a public function data plane endpoint,
- a **sync** (`@fn.sync`) — DuckLake-native ingestion,
- a **schedule** (`schedule=` on the factory) — durable cron runs.

A scheduled function whose body calls `agent.run()` is also how you run an **agent** on a schedule — there is no separate agent scheduler. See `limilake docs agents`.

## Anatomy

```python
import limilake
from limilake import logger

fn = limilake.function(
    id="123e4567-e89b-42d3-a456-426614174000",  # Contract v2 durable identity
    name="daily-report",
    description="Build the daily invoice report",
    access="private",
    run_as="caller",
)


@fn.action
def run(payload: dict[str, str]) -> dict[str, str]:
    rows = limilake.lake.read_table("bronze.invoices")
    logger.info(f"read {len(rows)} rows")
    return {"status": "ok", "requested_by": payload["requested_by"]}
```

`limilake add function` follows the Workspace Contract in `limilake.toml`.
Contract v2 generates the durable `id`; preserve it when moving or editing the
Function, and generate a new ID when copying the Function into a new item.
Contract v1 does not define `id`, so its compatibility scaffold omits that
keyword. Use `limilake workspace migrate` to add durable identities and advance
an initialized Contract v1 Workspace to v2. `name` is its human-readable label.
`description` explains what the
Function does to people and agents; for an MCP-exposed Function, it is also the
first paragraph of the projected tool description. Keep it short, specific, and
current.

Inside an `except` block, use `logger.exception("daily report failed")` to log
the message together with the current exception traceback. Use `logger.error`
when there is no active exception to attach.

An action or sync declares either no parameter, or one required
`dict[str, T]` parameter. LimiLake delivers the complete run input JSON object
as that one argument; object fields are not mapped onto Python parameters by
name. Scalar parameters, multiple parameters, and parameter defaults are
invalid. A zero-parameter handler ignores the input object.

Managed delivery populates the governed runtime before your code runs. During
`limilake dev`, a deliberate local action instead starts without platform
authority: `logger` works immediately, while lake, AI, Connection, Document,
Secret, and Agent capabilities bootstrap when your code first uses them. Keep
governed module attributes such as `limilake.lake` inside the handler so the
module can be imported before that capability is needed. Without an available
CLI session, first use fails the local run with the actionable
`capability_unavailable` error.

There is no `def run(ctx):` wrapper and no manual import of credentials. Data
access is scoped by the function's mounts, and providers are reached through
`limilake.connections` (the egress gateway), never as raw secrets. Lazy local
bootstrap changes when authority is acquired; the platform still authorizes
every governed operation live.

## Decisions

`limilake.ai.decide` asks typed questions about a piece of state and returns
typed answers in one call. Requests name the `systemone` decision role, not a
model: the platform maps the role to its current decision model, and each
result reports the model that answered in `model` (`None` when the response
did not name one).

```python
import limilake


@fn.action
def triage(payload: dict[str, str]) -> dict[str, object]:
    ticket = {"subject": payload["subject"], "body": payload["body"]}
    team = limilake.ai.decide.choice(
        ticket,
        "Which team should handle this ticket?",
        {"billing": "Invoices and payments", "support": "Product problems"},
    )
    urgency = limilake.ai.decide.score(
        ticket, "How urgent is this ticket?", ["can wait", "this week", "today"]
    )
    refund = limilake.ai.decide.noul(ticket, "The customer asks for a refund.")
    return {
        "team": team.answer.choice,
        "urgency": urgency.answer.score,
        "refund": refund.answer.noul > 0.5,
    }
```

- `choice(state, instructions, criteria)` picks one key of `criteria` (option
  name to description). The answer carries per-option `probabilities` and a
  `confidence` when the model reports them. A choice outside `criteria`, or a
  probability or confidence outside 0 to 1, raises `LakeProxyError`.
- `score(state, instructions, levels)` places the state on ordered levels,
  lowest first. `answer.score` runs from `0` (the first level) upward, and
  `answer.legend` maps level keys back to your levels.
- `noul(state, instructions, criteria=None)` returns the probability, from 0
  to 1, that the statement in `instructions` is true. The optional `criteria`
  describes what `"true"` and `"false"` mean.
- `ask(state, questions)` sends several questions in one call. `questions`
  maps your own ids to `{"type": ..., "instructions": ..., "criteria": ...}`
  objects, and the result's `answers` uses the same ids.

`state`, `instructions`, and criteria accept a string or any JSON value. Every
question of a successful call counts as one decision against the Tenant's
monthly `decision:systemone` package, and a request carries at most 512
questions in a body of at most 1 MiB. Invalid questions raise `ValueError` before a
request is sent. Gateway refusals raise `LakeProxyError` with the gateway
status and code: `402` for billing, `403` when the resource is not allowed,
and `429` for limits.

## Access and execution identity

Functions declare two separate choices:

- `access="private" | "api_key" | "public"` controls who may invoke it.
- `run_as="caller" | "assigned"` controls whose live tenant authority the runtime uses.

The valid combinations are `private+caller`, `private+assigned`,
`api_key+assigned`, and `public+assigned`. Private caller mode is the default.
Caller-less access must use an assigned identity.

The first publish of a new `run_as="assigned"` function assigns the linked
Tenant Identity of the authenticated publisher. Git author and committer fields
are never trusted for authority. Later code pushes preserve that assignment;
an explicit reassignment or security-mode change revalidates through the same
server policy. At runtime the identity, human membership, and workspace
authority are checked live, so offboarding or lost authority fails closed until
the function is reassigned.

The older `auth=` spelling remains a deprecated compatibility alias. New code
should use `access=` and `run_as=`.

### Who is calling

`limilake.caller()` tells a Function which person it is serving:

```python
import limilake

caller = limilake.caller()      # limilake.Caller | None
if caller is not None:
    caller.tenant_user_id       # UUID, stable for this person in this Tenant
    caller.display_name         # "Anna Svensson" (falls back to the email)
    caller.email
    caller.access_level         # "viewer" | "member" | "owner" | None
    caller.initials             # "AS"
```

The platform resolves the caller server-side; never decode the sandbox token
yourself.

| Invocation | `limilake.caller()` |
|---|---|
| HTTP route, `run_as="caller"` | The caller |
| Deliberate run from the portal, CLI, or a published App | The person who started it |
| Schedule, Agent runtime | `None` |
| HTTP route, `run_as="assigned"` (including `api_key` and `public`) | Raises `limilake.CallerUnavailableError` |
| Local `limilake dev` | The developer, with `access_level=None` |

`None` means there is no human caller. `CallerUnavailableError` (its `reason`
is `not_propagated`, `profile_unavailable`, `no_credential`, `rejected`, or
`unreachable`) means one may exist but is not revealed, so refuse the write
instead of attributing it to nobody. Use `run_as="caller"` when a route must
know who is calling. The `tenant_user_id` equals the `viewer.tenant_user_id` a
published App sees, so an App and its Functions agree on who the person is.
The caller is display and attribution data: it grants nothing, and the email
it carries is the App author's responsibility once stored or sent anywhere.

## Publication and execution

There is no separate Function deployment. Pushing the complete Workspace
Revision to `main` publishes its source. Once that revision is indexed, valid
Function routes and code schedules become current from that accepted `main`.
The same push queues an exact-SHA Build; successfully built App artifacts
activate automatically. Invoking the Function later creates a Function Run; it
does not publish source.

Create the contract-shaped Function in the normal Workspace checkout, edit its
fixed entrypoint, and publish the complete revision with Git:

```bash
limilake add function daily-report
# edit functions/daily-report/function.py
git add -- functions/daily-report/function.py
git commit -m "Add daily report Function"
git push origin HEAD:main
limilake function list                       # see Functions indexed from main
limilake publication show
limilake function show functions/daily-report/function.py --workspace my-ws
limilake function logs functions/daily-report/function.py --workspace my-ws
```

`limilake publication show` inspects the asynchronous Build and App-artifact
activation. Function commands do not wait for App activation; they resolve the
latest indexed `main` Function and its Runs.

`limilake function deploy` is a retained convenience for committing named local
Function files directly to a Workspace branch. It is not a separate deployment
or activation path: with its default `--branch main`, the resulting accepted
revision enters the same main-indexing and exact-SHA Build flow as a Git push.
The fixed entrypoint may be written as either
`functions/daily-report/function` or `functions/daily-report/function.py`; both
address the same file. If the selected branch already contains those bytes, the
command succeeds with `changed: 0` and creates no commit, indexing event, or
Build.

## Running

- **Live (default):** `limilake function invoke <function>` runs it server-side in a real sandbox — true production parity.
- **Standalone local:** `limilake function invoke <function> --local` and `limilake function serve` run the function in your workspace venv against live data and egress, for breakpoints and hot reload. These commands currently resolve the CLI session before starting the runtime.
- **Workspace dev loop:** `limilake dev` runs deliberate local actions through the Workspace runtime without requiring a session for pure code or logging. Governed capabilities bootstrap only when used; HTTP Functions still require the CLI session because their long-lived serve runtime starts eagerly.

Every deliberate-invocation surface uses that same object:
`limilake function invoke --input '{"requested_by":"agent"}'`, the generated
Workspace client, `@limilake/client`, and the documented run HTTP endpoint.
Omitting input sends an empty object. Generated clients expose a no-argument
method for a zero-parameter handler and a typed object argument for a
`dict[str, T]` handler; their completed result type also follows the documented
result value envelope.

In every mode, governed data, AI, and egress calls hit the live platform and use
live server authorization. Only pure deliberate actions in the Workspace dev
loop can complete without contacting it.

---

<!-- getting-started.md -->

---
title: Getting started
slug: getting-started
summary: Install the CLI, authenticate, link a workspace, and run your first query.
---

# Getting started

Use the [CLI command reference](./cli-reference.md) for command examples,
common flags, and pagination rules, or run `limilake docs cli-reference`
offline. `limilake <noun> --help` lists its actions without signing in.

To apply your linked checkout consistently to scoped commands, opt into
`--workspace-policy linked` (or `LIMILAKE_WORKSPACE_POLICY=linked`). Explicit
`--workspace` overrides environment values, which override the checkout. App,
Connection, Execution, Lakehouse, Secret, and Table lists accept
`--all-workspaces` for aggregate results. File and Shortcut lists accept it to find
one Lakehouse across Workspaces, then list only that target's contents. Duplicate
names require the UUID from `limilake lakehouse list --all-workspaces`.
The flag overrides ambient Workspace defaults, conflicts with explicit
`--workspace`, and is unavailable to Workspace-bound credentials, including bound
token sessions. Paging remains separate: add `--all` where supported to read every
page.

Use `--deadline 30s` (or `LIMILAKE_DEADLINE`) to bound discovery, requests,
retries, and polling together. An earlier operation or caller deadline wins.
Legacy Workspace defaults and `--timeout` meanings remain for two subsequent
stable releases and at least 30 days, until an announced breaking release;
explicit legacy policy and operation-scoped timeout use print a stderr notice.

LimiLake is a multi-tenant data lake platform: **workspaces** hold **lakehouses**, lakehouses hold **schemas**, and schemas hold **tables** and **files**. Code lives as **functions** (`.py`) and **apps** (`.app.tsx`) in the workspace git repo; ordinary files such as `README.md` are valid Workspace source as well.

## 1. Install the CLI

The supported CLI is one signed `limilake` binary. It does not require Python,
Node.js, or a repository checkout. The first public matrix is:

| Operating system | Architectures |
| --- | --- |
| Linux | AMD64 (`x86_64`) and ARM64 (`aarch64`) |
| macOS | AMD64 (Intel) and ARM64 (Apple Silicon) |

Windows is not supported by the initial release.

For the stable channel, use the verified convenience installer:

```bash
curl -fsSL https://get.limilake.com/ | sh
limilake --output json version
```

The version command reports the semantic version, exact source commit, Go
toolchain, operating system, and architecture. To review the installer before
running it, or to install into a managed path:

```bash
INSTALLER=$(mktemp)
curl -fsSL https://get.limilake.com/ -o "$INSTALLER"
sh -n "$INSTALLER"
sh "$INSTALLER" --channel stable --install-dir "$HOME/.local/bin"
```

Use `--no-modify-path` when your shell profile or managed environment owns
`PATH`. Resolve and install the exact current stable version with immutable
version selection:

```bash
VERSION=$(curl -fsSL https://packages.limilake.com/cli/channels/stable)
curl -fsSL https://get.limilake.com/ | sh -s -- --version "$VERSION"
limilake --output json version
```

The selected version's immutable manifest, signatures, direct archives, SBOMs,
provenance, source, notices, and Agent context are published under:

```text
https://packages.limilake.com/cli/v$VERSION/
```

The GitHub Release for `cli/v$VERSION` is an internal audit record for
authorized repository readers. It names the source commit, public-key
fingerprints, artifact digests, and native acceptance evidence, but it is not a
public trust anchor. Released version paths are immutable. For an external
trust bootstrap, obtain the approved public-key digest through an independently
controlled channel; the package origin's copy is not its own trust anchor.

```text
https://github.com/liminityab/limilake-v2/releases/tag/cli/v$VERSION
```

### Update, rollback, replace, or uninstall

Executable updates are explicit. Bare `limilake` and root `limilake --help`
may perform one anonymous stable-channel check behind a private 24-hour cache
and print an advisory notice on stderr. Subcommands, subcommand help, version
output, and machine-readable output do not check for updates automatically.
The CLI sends no usage telemetry. Use an explicit signed check to compare the
installed and stable versions, and `upgrade` to install the selected release:

```bash
limilake --version --check
limilake version --check --output json
limilake upgrade --channel stable
```

The explicit check verifies the stable manifest signature within five seconds
(or a shorter `--timeout`). It reports installed/latest versions and their source
commits, plus the exact `limilake upgrade --version VERSION` command. An
available update exits 0; a failed check exits 6. If the signed release has no
artifact for your platform, the check reports `unsupported_platform` and leaves
`upgrade_command` empty. Development builds report an
unknown comparison; newer builds are identified without a downgrade. No archive
is downloaded and no executable is replaced by a check. `update` remains an
alias with its existing behavior and output.

The same check reports executable/PATH candidates and possible shadowing.
Shell aliases and cached commands require a check inside your own shell:

```bash
type -a limilake
hash -r
```

If it finds an old Python launcher or uv tool environment, identify the old
installation before removing it. `uv tool list` lists installed tools. If it
lists the old `limilake` CLI package, use `uv tool uninstall limilake`. For an
editable virtualenv installation, use that environment's
`uv pip uninstall limilake` only after confirming it is the old CLI environment;
the current Python SDK/runtime is a separate product. Then install the signed
CLI and refresh your shell's command cache:

```bash
curl -fsSL https://get.limilake.com/ | sh
hash -r
type -a limilake
limilake version --check
```

Put the intended installation directory first in PATH if another executable
still takes precedence. The check does not uninstall, install, or repair paths.

To roll back, select an earlier verified immutable version. A failed download,
signature check, digest check, or executable replacement leaves the current
binary usable:

```bash
limilake update --version <previous-version>
limilake --output json version
```

For a manual replacement after completing the direct verification below,
stage the verified binary beside the destination and move it into place:

```bash
mkdir -p "$HOME/.local/bin"
REPLACEMENT=$(mktemp "$HOME/.local/bin/.limilake.XXXXXX")
install -m 0755 "$VERIFY_DIR/limilake" "$REPLACEMENT"
mv -f "$REPLACEMENT" "$HOME/.local/bin/limilake"
```

To uninstall a per-user installation, first confirm the resolved path, then
remove only that executable. Project files, profiles, and the managed Build
toolchain cache are separate and are not removed automatically:

```bash
command -v limilake
rm "$HOME/.local/bin/limilake"
```

The CLI keeps its exact version-matched Node, pnpm, Python, and uv Build
toolchain under the operating system user cache at
`<user-cache>/limilake/build-toolchains/v1/cli-v<version>/<os>-<arch>/`.
Inspect it without network access or disk mutation:

```
limilake toolchain doctor
limilake --output json toolchain doctor
```

If the report says `missing`, `invalid`, or `incompatible`, restore the exact
signed cohort atomically:

```
limilake toolchain repair
```

Repair verifies a complete sibling replacement before changing the selected
cache. A failed repair leaves any previously selected valid toolchain intact.
Use `limilake toolchain repair --offline` when network access is prohibited; it
repairs local selection state when possible and otherwise returns a stable JSON
diagnostic with the exact next action when global `--output json` is selected,
instead of contacting the package origin.

Do not delete the cache as a first repair step. If `doctor` reports changed
bytes, a missing runtime file, or an interrupted replacement, run `repair`; it
restores the exact signed cohort and cleans only the version-scoped interrupted
state. Then verify the recovered path without network access:

```text
limilake --output json toolchain doctor
limilake build --offline
```

CLI updates and rollbacks keep separate version-scoped toolchain entries. After
selecting an earlier release, inspect that exact version's cache before
building:

```text
limilake update --version <previous-version>
limilake --output json toolchain doctor
limilake toolchain repair                 # only when that exact cache is unavailable
```

Every signed CLI publication is gated by clean-machine Builds on Linux
AMD64/ARM64 and macOS AMD64/ARM64. The release record binds one witness per
target to the exact CLI archive, CLI SBOM, Build-toolchain bundle, toolchain
SBOM, manifest, and provenance identities. Those witnesses exercise
acquisition, reuse, offline mode, doctor, corruption/interruption repair,
update, and rollback without a repository checkout or host Node, pnpm, Python,
uv, or `workspace-build`.

These cache commands govern an ordinary signed standalone CLI installation.
The hosted LimiLake Agent image deliberately sets an image-owned Build Engine
override and supplies its tools from the pinned image. In that environment,
`limilake build` does not use this managed cache, and `toolchain doctor` or
`repair` does not describe or change the active Build path.

### Verify a direct download

For a managed or manual exact-version install, obtain the approved public-key
digest through an independently controlled channel before trusting the package
origin's copy. Authorized maintainers may use the private GitHub Release as an
additional internal audit record. Linux verifies the raw Ed25519 signature with
OpenSSL:

```bash
VERSION=$(curl -fsSL https://packages.limilake.com/cli/channels/stable)
BASE="https://packages.limilake.com/cli/v${VERSION}"
VERIFY_DIR=$(mktemp -d)

curl -fsSL "$BASE/release-public-key.pem" -o "$VERIFY_DIR/release-public-key.pem"
curl -fsSL "$BASE/release-public-key.sha256" -o "$VERIFY_DIR/release-public-key.sha256"
sha256sum "$VERIFY_DIR/release-public-key.pem"
(cd "$VERIFY_DIR" && sha256sum -c release-public-key.sha256)

curl -fsSL "$BASE/manifest.json" -o "$VERIFY_DIR/manifest.json"
curl -fsSL "$BASE/manifest.json.sig" -o "$VERIFY_DIR/manifest.json.sig.b64"
openssl base64 -d -A -in "$VERIFY_DIR/manifest.json.sig.b64" -out "$VERIFY_DIR/manifest.json.sig"
openssl pkeyutl -verify -pubin \
  -inkey "$VERIFY_DIR/release-public-key.pem" -rawin \
  -in "$VERIFY_DIR/manifest.json" -sigfile "$VERIFY_DIR/manifest.json.sig"
```

Stock macOS uses OpenSSH rather than Apple LibreSSL for the same signed
manifest. Compare the SHA-256 of `release-public-key.pub` with the approved
digest from that independently controlled channel, then verify the SSHSIG
namespace:

```bash
VERSION=$(curl -fsSL https://packages.limilake.com/cli/channels/stable)
BASE="https://packages.limilake.com/cli/v${VERSION}"
VERIFY_DIR=$(mktemp -d)

if ! curl -fsSL "$BASE/release-public-key.pub" \
  -o "$VERIFY_DIR/release-public-key.pub"; then
  echo "Release $VERSION predates stock macOS direct verification; use the verified installer or select a newer exact release." >&2
  exit 1
fi
curl -fsSL "$BASE/manifest.json" -o "$VERIFY_DIR/manifest.json"
curl -fsSL "$BASE/manifest.json.sshsig" -o "$VERIFY_DIR/manifest.json.sshsig"
shasum -a 256 "$VERIFY_DIR/release-public-key.pub"
printf 'limilake-release namespaces="limilake-cli-manifest" ' \
  > "$VERIFY_DIR/allowed-signers"
cat "$VERIFY_DIR/release-public-key.pub" >> "$VERIFY_DIR/allowed-signers"
ssh-keygen -Y verify \
  -f "$VERIFY_DIR/allowed-signers" \
  -I limilake-release \
  -n limilake-cli-manifest \
  -s "$VERIFY_DIR/manifest.json.sshsig" \
  < "$VERIFY_DIR/manifest.json"
```

After the manifest signature passes, select the archive for the machine and
verify its signed digest before extraction:

```bash
case "$(uname -s):$(uname -m)" in
  Linux:x86_64) OS=linux; ARCH=amd64 ;;
  Linux:aarch64) OS=linux; ARCH=arm64 ;;
  Darwin:x86_64) OS=darwin; ARCH=amd64 ;;
  Darwin:arm64) OS=darwin; ARCH=arm64 ;;
  *) echo "Unsupported platform" >&2; exit 1 ;;
esac
ARTIFACT="limilake_${VERSION}_${OS}_${ARCH}.tar.gz"
DIGEST=$(awk -v target="cli/v${VERSION}/${ARTIFACT}" '
  index($0, "\"path\": \"" target "\"") { matched = 1; next }
  matched && index($0, "\"sha256\": \"") {
    line = $0
    sub(/^.*"sha256": "/, "", line)
    sub(/".*$/, "", line)
    print line
    exit
  }
' "$VERIFY_DIR/manifest.json")
test -n "$DIGEST"
curl -fsSL "$BASE/$ARTIFACT" -o "$VERIFY_DIR/$ARTIFACT"
if command -v sha256sum >/dev/null 2>&1; then
  ACTUAL=$(sha256sum "$VERIFY_DIR/$ARTIFACT" | cut -d' ' -f1)
else
  ACTUAL=$(shasum -a 256 "$VERIFY_DIR/$ARTIFACT" | cut -d' ' -f1)
fi
test "$ACTUAL" = "$DIGEST"
tar -xzf "$VERIFY_DIR/$ARTIFACT" -C "$VERIFY_DIR" limilake
"$VERIFY_DIR/limilake" --output json version
```

The reviewed installer performs these signature, archive-shape, digest,
permission, and atomic replacement checks automatically.

### Installation troubleshooting

- **`limilake: command not found`:** start a fresh shell, or add
  `$HOME/.local/bin` to `PATH`. Use `--install-dir` and `--no-modify-path` in a
  managed environment.
- **Signature or digest failure:** stop. Do not bypass verification or reuse a
  partial download. Compare the public-key digest and artifact digest with the
  approved digest from an independently controlled channel. Authorized
  maintainers may also inspect the private GitHub Release audit.
- **macOS Keychain or Linux Secret Service unavailable:** interactive logins
  use the OS credential store when it is unlocked. Headless Linux falls back to
  `~/.limilake/credentials.json` with mode `0600`; prefer `LIMILAKE_TOKEN` or
  `LIMILAKE_TOKEN_FILE` for stateless automation.
- **Failed update:** run the existing binary's version command. If its identity
  is unchanged, retry the exact immutable version or restore a previously
  verified release. Do not delete the managed toolchain cache as a first step.

## 2. Authenticate

```
limilake auth login --host app.limilake.com --profile work
```

This runs a device-flow OAuth login and stores a tenant-bound access/refresh
bundle in your OS keyring (or the private headless fallback described above).
You sign in yourself.

An agent can return the verification URL and code to you without blocking:

```bash
limilake auth login --host app.limilake.com --profile work --no-wait --output json
limilake auth status --profile work --output json
```

`--no-wait` exits 0 with `state:pending`, `url`, `user_code`, expiry, polling
interval, and the exact `poll_command`. Open the URL yourself and enter the code.
No credentials are created for another person. Use the returned polling command;
the profile becomes active only after successful sign-in. Each `auth status`
performs at most one due poll. Pending authorization exits 3 and includes its
next poll time; a too-early poll makes no request. Follow any longer interval
reported after a server slow-down. Denial or expiry also exits 3 with login
recovery guidance. Successful status retains its usual identity result and exits
0. Blocking login is still the default. Repeating `--no-wait` returns the existing
live pending login without creating another code or changing its host/Tenant.
The hint names the retained host/Tenant. If new options differ, it states that
they were not applied. A redeemed challenge returns `state:finalizing`, blank URL/code,
and the status command to finish saving credentials. Add `--restart` to explicitly
discard that pending state and begin again.

The CLI stores the private device code in
`~/.limilake/pending-login/<profile>.json`, bounded to 32 KiB with mode `0600`
in a private directory, bound to your OS user, profile, host and requested
Tenant. After redemption, the same file temporarily holds the access **and
refresh** tokens, even when an OS keyring is available. This allows `auth status`
to retry interrupted live validation, Git setup or credential saving without
redeeming the code again. Tokens can remain in that file after a transient error.

The original device-authorization deadline bounds retries, including staged
tokens; access-token expiry alone does not discard a valid refresh token. The
next `auth status` or login clears expired state; there is no background cleanup
while the CLI is idle. Successful completion, denial, explicit `--restart`,
logout and profile deletion also clear it atomically to a null record. The CLI
never prints the private device code or tokens. Concurrent
polls cannot redeem the same challenge twice, and a pending login cannot replace
a profile that changed while you were signing in. This local saved-profile flow
cannot be combined with `--token-stdin` or an environment-injected credential.

Select another tenant only through the server-verified switch:

```
limilake tenant list --profile work
limilake tenant use <tenant-id-or-slug> --profile work
limilake context --profile work
```

Headless or CI? Import a personal access token through stdin (never an argv value):

```
printf '%s' "$LIMILAKE_PAT" | limilake auth login --token-stdin \
  --host app.limilake.com --profile ci
```

For stateless environment authentication, set `LIMILAKE_TOKEN`, `LIMILAKE_HOST`, and `LIMILAKE_TENANT_ID` together. The Tenant ID is always required and must match the checkout's Tenant binding when you run from a linked checkout. PATs are tenant-bound and cannot switch.

A token session, whether a PAT profile or `LIMILAKE_TOKEN`, authenticates as a shared user with no tenant-scoped identity. That is enough for every source workflow: pushing `main` is authorized by the Git session itself. The retained `limilake publication rollback` recovery command still needs an attributable device-flow profile. You can create a PAT from an OAuth profile:

```
limilake auth token create ci-token --days 90 --profile work
```

Check who you are at any time:

```
limilake auth status --profile work
```

## 3. Find your data

```
limilake workspace list
limilake lakehouse list --workspace my-workspace
limilake table list --lakehouse my-lakehouse
```

`limilake lakehouse explain <name>` blends the live schema with the concept doc, so you can learn a lakehouse without leaving the terminal.

## 4. Query

```
limilake query "SELECT * FROM bronze.invoices LIMIT 10" --lakehouse my-lakehouse
```

Queries are read-only and bounded; they run through the platform's Lake Query API,
so no local data engine is needed.

## 5. Author code

Workspace bootstrap creates the repository. Clone and link it in one step:

```
limilake workspace clone my-workspace
cd my-workspace
```

`workspace clone` runs ordinary Git against the canonical remote the platform
advertises, configures Git credentials for the new checkout, and links it. To do
it by hand instead, clone the `clone_url` from
`limilake --output json workspace show my-workspace` and run
`limilake workspace link my-workspace` inside the checkout. A fresh machine
needs the signed CLI and Git 2.49+ on PATH, then your interactive `auth login`.
If ordinary Git's credential helper needs repair, run
`limilake auth setup-git --profile work` for the selected profile.

Use an absolute destination to clone independently of your current directory.
Git creates any missing parent directories:

```bash
limilake workspace clone my-workspace "$HOME/projects/my-workspace"
limilake workspace clone my-workspace "$HOME/projects/my-workspace" --no-link
```

`--link` is the default; the last `--link`/`--no-link` value wins. `--no-link`
skips the local Workspace binding while keeping the newly cloned repository's
Git credential helper. It does not remove an existing binding. Repeating clone
reuses a checkout with the matching canonical remote and binding; it can
finish linking a matching unlinked checkout. Reused checkouts keep their
existing Git configuration; use `auth setup-git` if ordinary Git
authentication needs repair. Unconfirmed checkout-root identities, nonempty
directories, and conflicting bindings are left untouched. Relative and default
destinations require an accessible current directory and a readable walk
through its ancestors; no existing checkout is required. Dangling, looping, or
non-directory destination parents fail with a path-specific usage error (exit
2) before Git starts; unreadable destinations or parents report permission
denied (exit 5). A rerun can use a symlinked parent: the checkout root is
matched by directory identity. If linking fails, the checkout remains and the
error prints the exact command to finish.

Commands that use the checkout's authentication context, including `auth status`,
`lake query`, and `ask`, stop before authentication if `.limilake/link.json`
cannot be read. Malformed JSON, a missing Workspace identity, or an invalid
profile name exits 2; an unreadable binding file exits 5. The error identifies
the checkout and failing file. These binding checks also apply to the clone
destination before Git starts.

A linked Git worktree without its own binding reads the main checkout's
`.limilake/link.json`, so `git worktree add` keeps the Workspace link.

`workspace status` inspects the binding from inside the checkout. It currently
exits 4 outside a checkout or before linking. `workspace init` scaffolds local
source, `workspace link` binds a checkout with the matching remote, and
`workspace clone` fetches and optionally links server source. Use
`workspace create` to provision a new server-side repository.

Add resources by name. `add` only ever writes files in your checkout:

```
limilake workspace init                    # only for a checkout without limilake.toml
limilake add function daily-report
limilake add app sales-dashboard
limilake add query active-customers
```

Edit `functions/daily-report/function.py` with your normal editor. The `add app`
result names the frozen dependency-install command that must succeed before the
local Vite loop can start; then refresh the generated client and start the loop:

```
pnpm install --frozen-lockfile --ignore-workspace
limilake generate --check
limilake dev
```

The loop binds `127.0.0.1` by default. For a browser on another machine over a
trusted private network, name one specific reachable interface and use stable
ports:

```text
limilake dev --host 100.64.0.10 --port 4300 --app-port-base 4301
```

The CLI prints the reachable App and Studio addresses. It refuses wildcard
hosts such as `0.0.0.0`; anyone who can reach the chosen interface can reach the
App previews and attempt trusted-host Local Studio requests. Open the exact
printed `http://<host>:<port>/studio/` URL. The page automatically supplies its
exact origin marker because Chrome may omit Fetch Metadata on private-network
HTTP; there is no token or browser setting to copy. Other browser origins still
cannot call Studio because the listener refuses their CORS preflight. If you do
not want a remote listener, keep the default and forward the same stable ports
over SSH:

```text
limilake dev --port 4300 --app-port-base 4301
ssh -L 4300:127.0.0.1:4300 -L 4301:127.0.0.1:4301 user@dev-host
```

Local Function execution also needs the version-matched `limilake[serve]`
Workspace runtime in `pyproject.toml` and `uv.lock`; `limilake add function`
prints that dependency step and the required `limilake-run` entrypoint.

Validate the complete Workspace with the same Build Engine used by production:

```text
limilake build
```

With an ordinary signed standalone CLI, the first Build prints the exact
managed Node, pnpm, CPython, and uv versions, immutable metadata URLs, transfer
bounds, and the per-user cache destination. After the signed manifest and
signature are verified, it prints the exact bundle and component sizes and
digests before downloading the bundle. Later Builds verify and reuse that exact
CLI-version cache. `limilake build --offline` performs no LimiLake-managed
acquisition, leaves the managed cache unchanged, and requires dependency
installation from the local pnpm store; it builds only when the compatible
cache is already present and valid.

Inside the hosted LimiLake Agent image, the same command uses the image-pinned
standalone Build Engine and base-image tools instead of the managed cache.
`--offline` is still forwarded to pnpm, but `toolchain doctor` and `repair` do
not govern that override.

Neither path is a network sandbox for Workspace code: local Vite configuration,
plugins, scripts, and child processes still run as the trusted local user. The
Workspace's `package.json`, `pyproject.toml`, and frozen lockfiles remain
authoritative.

## Publish a Workspace

Pushing an accepted revision to the protected `main` branch is the publication
action. The platform builds that exact SHA and automatically activates a
successful Build; there is no second Publish command.

**Human Git credentials can push only `main` and `drafts/workspace`.** Local
feature branches are fine: the explicit `HEAD:<target>` commands below send
your current commit to a supported remote ref, regardless of your local branch
name. Pushing a feature branch by its own name, such as
`git push origin my-feature`, is rejected. Remote feature branches and tags
are not supported push targets.

Git pushes commits. Saving a file or running `limilake add` does not commit it.
Review and stage the files you intend to publish, including any changed
Workspace manifests, lockfiles, and generated clients, then create a commit.
For example, after editing `README.md`:

```bash
git status --short
git diff -- README.md
git add -- README.md
git diff --cached
git commit -m "Update workspace notes"
```

Replace `README.md` with the paths you changed. Only the committed revision
will be pushed; untracked files and uncommitted edits stay on your machine.

To save that commit to the shared editor Draft:

```
git push origin HEAD:drafts/workspace
```

For a direct Git workflow, push `main` itself (the same human credential is
allowed to fast-forward both refs when it has Workspace write access):

```
git push origin HEAD:main
```

The Draft step is optional. If you saved the commit to the Draft first, the
same `HEAD:main` command publishes it. A push that updates both refs at once is
rejected; push each ref separately. The Draft is shared with the editor and
other collaborators, so fetch and reconcile its changes before pushing when
it has advanced.

Every accepted `main` push queues one exact-SHA production Build and then
activates it automatically. A Draft-only push remains work in progress and is
not built for production until that revision reaches `main`. Work that exists
only in your local checkout is never part of a Publication. A Contract-v2
revision may contain Apps, Functions, both, or neither; a revision containing
only `README.md` still builds and activates a valid no-op Deployment Manifest.

Repositories created before `limilake.toml` existed are also accepted by the
delivery Build as historical Contract v1 when they contain no executable
resources. A present-but-invalid marker still fails closed.

The delivery attempt is durable and can be inspected with
`limilake publication show`. While a Build or activation is queued, running, or
failed, the previous Publication keeps serving. A transient activation failure
is retried by the worker; a terminal Build failure names its diagnostic and
does not switch traffic.

`limilake publication rollback` returns to a retained Deployment Manifest. It is
pointer movement over artifacts that were already built, so it never runs a
Build. Read the manifest id from `limilake publication show`; a manifest that has
left the retention window is refused rather than rebuilt.

Every attempt field, including `build_id`, `deployment_manifest_id`,
`publication_id`, `pointer_generation`, `conflict_paths`, and `failure_code`,
is carried verbatim by `--output json` and `--output yaml`. A conflict that
reported no paths keeps its empty `conflict_paths` list, and an attempt that
never conflicted has none at all, so the two stay distinguishable in a script.

There is no attempt history listing yet. `limilake publication show` reads the
newest delivery, or one attempt by id, so record ids you want to keep.

### Git push troubleshooting

Push rejections name the problem, the target ref and available file location,
and the next action. The same rejection appears in CLI commands that commit
files. For example:

```text
rejected: Function input parameter has a default value — where: refs/heads/main functions/daily-report/function.py:26 — fix: Remove the default value from parameter run_input. — more: limilake explain function_handler_signature_unsupported — correlation: <id> [code=function_handler_signature_unsupported]
```

Run `limilake explain function_handler_signature_unsupported` for the recovery
instructions without a network connection or login. Use the code from your own
error for other rejections. Keep the correlation ID when reporting a problem;
it lets support find the server diagnostic without copying private source or
credentials into a report.

Find the recovery step for
[handler signatures](./push-rejections.md#function_handler_signature_unsupported),
[unsupported refs](./push-rejections.md#git_ref_not_allowed),
[Contract-v1 migration evidence](./push-rejections.md#contract_v1_migration_ambiguous),
[non-fast-forward updates](./push-rejections.md#git_non_fast_forward),
[concurrent ref changes](./push-rejections.md#git_conflict),
[authentication](./push-rejections.md#git_authentication_required),
[write access](./push-rejections.md#git_authorization_denied),
[size limits](./push-rejections.md#git_size_limit), or
[all rejection codes](./push-rejections.md#code-index).

- **[`[code=git_ref_not_allowed]`](./push-rejections.md#git_ref_not_allowed):** keep the local branch
  and push its commit with `git push origin HEAD:drafts/workspace` for work
  in progress, or `git push origin HEAD:main` to publish. The remote target
  must be one of those two refs.
- **[`[code=git_multi_ref_unsupported]`](./push-rejections.md#git_multi_ref_unsupported):** the push
  tried to update `main` alongside another ref. Push the Draft and `main`
  in separate commands as shown above.
- **`Everything up-to-date`, but your changes are missing:** run
  `git status --short` and `git log -1 --oneline`. Commit the intended files
  and push that commit to the intended ref. An unchanged `main` does not
  request a new Build.
- **Authentication failure or HTTP 401:** check `limilake context` inside
  the checkout, then authenticate again with
  `limilake auth login --host app.limilake.com --profile work`.
  If Git's helper is missing, run `limilake auth setup-git --profile work`.
  Use `limilake workspace doctor` to check the linked Workspace, remote, and
  credential helper. Use your profile name in place of `work`.
- **HTTP 403:** verify the Tenant and Workspace in `limilake context` and
  confirm live member or owner access. Viewers cannot push. A personal access
  token also needs `workspace:write`; a broad token does not replace live
  Workspace access. A Tenant administrator with Workspace administration
  authority has owner access without a separate Workspace membership.
- **Non-fast-forward rejection:** another commit is already on the target
  branch. For `main`, run `git fetch origin`, merge `origin/main` into your
  local branch, resolve and commit any conflicts, then retry
  `git push origin HEAD:main`. For a Draft push, reconcile with
  `origin/drafts/workspace` instead. Human credentials cannot force-push or
  delete either authoring ref, including `main`, even with owner access.
- **Workspace source validation rejection:** `main` validates the complete
  revision before accepting it. Follow the file, line, and diagnostic in the
  remote error. For example, an `@fn.action` or `@fn.sync` input parameter
  must not have a default: use
  `def run(payload: dict[str, str]) -> dict[str, str]:` instead of
  `def run(payload: dict[str, str] = None) -> dict[str, str]:`. A handler
  that needs no input and returns nothing can use `def run() -> None:`.
  Every handler needs a return annotation matching what it returns.
  Read `limilake docs functions`, then run `limilake build`, commit the
  correction, and retry the push.
- **Other remote hook rejection:** keep the complete `remote:` error, target
  ref, and time. Successful authentication does not mean the ref or Workspace
  source was accepted. Check that the push names one supported ref; for a
  source validation error, correct the named file and run `limilake build`
  before committing and retrying. Run `limilake docs reporting-problems`
  for instructions to share a reproducible failure.

## Output formats

Every command accepts a global `--output table|json|yaml` (default `table`), so the same commands serve humans and scripts.

Use `limilake profile list|show|use|delete` for named environments. In parallel shells, set `LIMILAKE_PROFILE` or pass `--profile` so one shell never changes the other's effective tenant. `limilake --output json context` is the scripting contract for the resolved profile, identity, tenant, workspace, credential kind/capabilities, and expiry.

## Command spelling and migration

Commands use singular nouns followed by actions: `agent show`, `execution show`,
`workspace update`, `user deactivate`, and `function commit`. The corresponding
`view`, `settings`, `remove`, and `deploy` spellings remain supported. Workspace
members use `workspace member list/add/remove/promote --workspace WORKSPACE`;
`promote` adds an owner without removing existing owners. User and role commands
still manage Tenant access. Provider discovery is available through either
`connection provider list/show` or `provider list/show`.

Select the explicit grant verbs with `--grammar canonical`:

```bash
limilake --grammar canonical credential grant list finance-api
limilake --grammar canonical credential grant create finance-api finance
limilake --grammar canonical credential grant delete finance-api finance --yes
limilake --grammar canonical lakehouse schema show finance
limilake --grammar canonical billing plan show
limilake --grammar canonical billing usage list
limilake billing grant list
```

The default grammar preserves older commands exactly: `credential grant list
finance` grants the credential named `list` to the Workspace `finance`. It does
not become a listing command. New Workspace member routes require a supplied
Workspace; grant creation and revocation keep both explicit positional targets.
Legacy spellings print migration guidance on stderr and remain supported for two
subsequent stable releases and at least 30 days, until an announced breaking
release. Grammar selection does not change output schemas.

---

<!-- push-rejections.md -->

---
title: Push rejection codes
slug: push-rejections
summary: Find the cause and recovery step for a Git or CLI source rejection.
---

# Push rejection codes

A source or ref validation rejection leaves the target ref unchanged. Read the
`where:` location and `fix:` action first. The trailer `[code=...]` identifies
the rejection for scripts; the correlation ID lets support find its server
record. CLI commands that commit files return the same rejection.

Run `limilake explain <code>` to read these recovery instructions offline,
without a profile or login. For example:

```bash
limilake explain function_handler_signature_unsupported
```

A Function handler's defaulted parameter needs a source correction. Remove the
default value from the named parameter, preserving its type, body, durable ID,
and return annotation. For example, change
`def run(run_input: dict[str, str] = {}) -> dict[str, str]:` to
`def run(run_input: dict[str, str]) -> dict[str, str]:`.
Then run `limilake build`, commit the corrected file, and retry the push.

For a Contract-v1 identity migration, the candidate's Function entrypoint must
match the Function evidence from the exact previous remote revision. Preserve
the existing paths and identities during the migration. Use
`limilake workspace migrate --dry-run` to inspect a local Contract-v1 migration,
then `limilake workspace migrate` to apply it before reviewing and committing
its changes. This local command cannot restore missing platform evidence. If
that evidence is missing or ambiguous, give support the correlation ID so an
administrator can reconcile it through the governed migration. Do not invent
replacement IDs or force-push to bypass identity admission.

See [Git push troubleshooting](./getting-started.md#git-push-troubleshooting)
for authentication, commit, and branch recovery steps, or
[Report a platform problem](./reporting-problems.md) to contact support.

## Code index

- [app_capability_unresolved](#app_capability_unresolved)
- [app_entrypoint_missing](#app_entrypoint_missing)
- [app_identity_duplicate](#app_identity_duplicate)
- [app_identity_invalid](#app_identity_invalid)
- [app_identity_missing](#app_identity_missing)
- [app_metadata_invalid](#app_metadata_invalid)
- [app_metadata_parse](#app_metadata_parse)
- [app_metadata_unknown_key](#app_metadata_unknown_key)
- [app_metadata_value_invalid](#app_metadata_value_invalid)
- [app_slug_invalid](#app_slug_invalid)
- [app_stray_file](#app_stray_file)
- [app_vite_config_ambiguous](#app_vite_config_ambiguous)
- [bootstrap_contract_version_invalid](#bootstrap_contract_version_invalid)
- [bootstrap_contract_version_missing](#bootstrap_contract_version_missing)
- [bootstrap_contract_version_unsupported](#bootstrap_contract_version_unsupported)
- [bootstrap_invalid](#bootstrap_invalid)
- [bootstrap_missing](#bootstrap_missing)
- [bootstrap_parse](#bootstrap_parse)
- [bootstrap_toolchain_channel_invalid](#bootstrap_toolchain_channel_invalid)
- [bootstrap_unknown_key](#bootstrap_unknown_key)
- [contract_v1_migration_ambiguous](#contract_v1_migration_ambiguous)
- [dependency_lockfile_drift](#dependency_lockfile_drift)
- [dependency_lockfile_invalid](#dependency_lockfile_invalid)
- [dependency_lockfile_missing](#dependency_lockfile_missing)
- [dependency_manifest_invalid](#dependency_manifest_invalid)
- [dependency_manifest_missing](#dependency_manifest_missing)
- [function_declaration_duplicate](#function_declaration_duplicate)
- [function_declaration_invalid](#function_declaration_invalid)
- [function_declaration_missing](#function_declaration_missing)
- [function_decorator_invalid](#function_decorator_invalid)
- [function_decorator_unsupported](#function_decorator_unsupported)
- [function_entrypoint_invalid](#function_entrypoint_invalid)
- [function_entrypoint_missing](#function_entrypoint_missing)
- [function_extractor_unavailable](#function_extractor_unavailable)
- [function_handler_signature_unsupported](#function_handler_signature_unsupported)
- [function_handler_unannotated](#function_handler_unannotated)
- [function_identity_duplicate](#function_identity_duplicate)
- [function_identity_invalid](#function_identity_invalid)
- [function_identity_missing](#function_identity_missing)
- [function_mcp_method_unsupported](#function_mcp_method_unsupported)
- [function_slug_invalid](#function_slug_invalid)
- [function_source_syntax](#function_source_syntax)
- [function_stray_file](#function_stray_file)
- [git_authentication_required](#git_authentication_required)
- [git_authorization_denied](#git_authorization_denied)
- [git_conflict](#git_conflict)
- [git_grant_expired](#git_grant_expired)
- [git_internal_error](#git_internal_error)
- [git_malformed_proposal](#git_malformed_proposal)
- [git_multi_ref_unsupported](#git_multi_ref_unsupported)
- [git_non_fast_forward](#git_non_fast_forward)
- [git_protected_ref_delete](#git_protected_ref_delete)
- [git_ref_not_allowed](#git_ref_not_allowed)
- [git_repository_denied](#git_repository_denied)
- [git_repository_purged](#git_repository_purged)
- [git_repository_unavailable](#git_repository_unavailable)
- [git_reserved_ref](#git_reserved_ref)
- [git_size_limit](#git_size_limit)
- [layout_not_directory](#layout_not_directory)
- [path_reserved](#path_reserved)
- [path_symlink_escape](#path_symlink_escape)
- [path_traversal](#path_traversal)
- [query_schema_contract](#query_schema_contract)
- [query_schema_invalid](#query_schema_invalid)
- [query_schema_missing](#query_schema_missing)
- [query_schema_orphaned](#query_schema_orphaned)
- [query_schema_version_unsupported](#query_schema_version_unsupported)
- [query_slug_invalid](#query_slug_invalid)
- [query_sql_invalid](#query_sql_invalid)
- [query_stray_entry](#query_stray_entry)
- [resource_identity_kind_reuse](#resource_identity_kind_reuse)
- [source_admission_rejected](#source_admission_rejected)
- [workspace_contract_not_activated](#workspace_contract_not_activated)
- [workspace_contract_regression](#workspace_contract_regression)

## app_capability_unresolved

An App capability names an undeclared resource.

**Fix:** Declare the referenced Function or Query, or remove its name from the App capability list.

## app_entrypoint_missing

The App entrypoint is missing.

**Fix:** Commit the configured App entrypoint, normally src/main.tsx, inside the App directory.

## app_identity_duplicate

Several Apps declare the same durable ID.

**Fix:** Restore each App's own durable UUID and assign a new UUID only to a newly created App.

## app_identity_invalid

The App's durable ID is invalid.

**Fix:** Set [app].id to its canonical lowercase hyphenated UUID.

## app_identity_missing

The App's durable ID is missing.

**Fix:** Add the App's canonical UUID as [app].id, preserving its existing identity during migration.

## app_metadata_invalid

App metadata is not a regular file.

**Fix:** Replace the App's limilake.toml with a regular TOML file.

## app_metadata_parse

App metadata contains invalid TOML.

**Fix:** Correct the App's limilake.toml syntax and run limilake generate --check.

## app_metadata_unknown_key

App metadata contains an unsupported key.

**Fix:** Remove unsupported keys using the App metadata schema.

## app_metadata_value_invalid

An App metadata value is invalid.

**Fix:** Correct the App metadata types, non-empty values and contained entrypoint path using the App schema.

## app_slug_invalid

The App directory name is invalid.

**Fix:** Rename the App directory to a lowercase slug using letters, digits and hyphens.

## app_stray_file

A file sits directly in the Apps area.

**Fix:** Move the file into its App directory or remove it from apps/.

## app_vite_config_ambiguous

The App has several Vite configuration files.

**Fix:** Keep one supported Vite configuration file in the App directory.

## bootstrap_contract_version_invalid

The Workspace Contract version is not an integer.

**Fix:** Use an integer for [workspace].contract in limilake.toml.

## bootstrap_contract_version_missing

The Workspace Contract version is missing.

**Fix:** Set contract under [workspace] in limilake.toml to the Workspace's supported Contract version.

## bootstrap_contract_version_unsupported

The Workspace Contract version is unsupported.

**Fix:** Upgrade the LimiLake toolchain or contact support for this Contract version; do not lower an existing Workspace's Contract version.

## bootstrap_invalid

The Workspace marker is not a readable regular file.

**Fix:** Replace limilake.toml with a regular UTF-8 TOML file.

## bootstrap_missing

The Workspace marker is missing.

**Fix:** Add a root limilake.toml with a supported [workspace].contract value.

## bootstrap_parse

The Workspace marker contains invalid TOML.

**Fix:** Correct the TOML syntax in limilake.toml and run limilake generate --check.

## bootstrap_toolchain_channel_invalid

The toolchain channel is invalid.

**Fix:** Set [toolchain].channel to a non-empty string or remove the optional toolchain table.

## bootstrap_unknown_key

The Workspace marker contains an unsupported key.

**Fix:** Remove unsupported keys from limilake.toml using the Workspace Contract schema.

## contract_v1_migration_ambiguous

Contract-v1 migration lacks exact expected-old Function identity evidence.

**Fix:** Preserve the existing Function paths and IDs; ask an administrator to reconcile the expected-old Function evidence through the governed migration using the correlation ID.

## dependency_lockfile_drift

A dependency lockfile does not match its manifests.

**Fix:** Run pnpm install or uv lock and commit the updated manifests and root lockfile together.

## dependency_lockfile_invalid

A dependency lockfile is invalid.

**Fix:** Regenerate the root lockfile with pnpm install or uv lock and commit it.

## dependency_lockfile_missing

A required dependency lockfile is missing.

**Fix:** Run pnpm install for Apps or uv lock for Functions and commit the root lockfile.

## dependency_manifest_invalid

A dependency manifest is invalid.

**Fix:** Correct the reported manifest's syntax and required fields, then refresh its lockfile.

## dependency_manifest_missing

A required root dependency manifest is missing.

**Fix:** Commit package.json for Apps or pyproject.toml for Functions at the Workspace root.

## function_declaration_duplicate

The Function has several declarations.

**Fix:** Keep exactly one top-level limilake.function declaration in function.py.

## function_declaration_invalid

The Function declaration is invalid.

**Fix:** Use supported literal limilake.function keywords and valid access and run_as values.

## function_declaration_missing

The Function declaration is missing.

**Fix:** Add one top-level limilake.function declaration to function.py.

## function_decorator_invalid

A Function handler decorator has an invalid shape.

**Fix:** Use @fn.action or @fn.sync without parentheses, or an HTTP decorator with one literal route path.

## function_decorator_unsupported

A Function handler decorator is unsupported.

**Fix:** Use a supported action, sync or HTTP handler decorator on the Function declaration.

## function_entrypoint_invalid

The Function entrypoint is not a regular file.

**Fix:** Replace function.py with a regular UTF-8 Python file.

## function_entrypoint_missing

The Function entrypoint is missing.

**Fix:** Commit function.py inside the Function directory.

## function_extractor_unavailable

The server's governed Python extractor is unavailable.

**Fix:** Ask support to restore the governed CPython 3.12 toolchain using the correlation ID.

## function_handler_signature_unsupported

The Function handler input cannot be delivered by the runtime.

**Fix:** For action/sync, use zero parameters or one required positional-or-keyword dict[str, T] input without a default; for HTTP, replace positional-only or variadic parameters with explicit typed positional-or-keyword or keyword-only parameters.

## function_handler_unannotated

A Function handler is missing type annotations.

**Fix:** Add type annotations to every handler parameter and its return value.

## function_identity_duplicate

Several Functions declare the same durable ID.

**Fix:** Restore each Function's own durable UUID and assign a new UUID only to a newly created Function.

## function_identity_invalid

The Function's durable ID is invalid.

**Fix:** Set the Function id to its canonical lowercase hyphenated UUID.

## function_identity_missing

The Function's durable ID is missing.

**Fix:** Add the Function's canonical UUID to limilake.function(id=...), preserving its existing identity during migration.

## function_mcp_method_unsupported

The MCP handler does not accept one JSON object.

**Fix:** Use a POST handler with exactly one object-shaped body parameter, or disable MCP exposure.

## function_slug_invalid

The Function directory name is invalid.

**Fix:** Rename the Function directory to a lowercase slug using letters, digits and hyphens.

## function_source_syntax

The Function contains invalid Python syntax.

**Fix:** Correct the Python syntax at the reported source location and run limilake generate --check.

## function_stray_file

A file sits directly in the Functions area.

**Fix:** Move the file into its Function directory or remove it from functions/.

## git_authentication_required

Git authentication is missing or invalid.

**Fix:** Run limilake auth login and limilake auth setup-git for your intended profile, then retry.

## git_authorization_denied

This credential cannot write this Workspace.

**Fix:** Check the selected Workspace and profile, ensure your PAT permits workspace:write, and ask an administrator to grant any missing write access.

## git_conflict

The remote ref or file changed since it was read.

**Fix:** Run git fetch origin, review the current remote branch and files, then retry with its current HEAD.

## git_grant_expired

The Git authorization has expired.

**Fix:** Run limilake auth login and limilake auth setup-git for your intended profile, then retry the push.

## git_internal_error

The server could not complete Git admission.

**Fix:** Retry once; if it fails again, give the correlation ID to support.

## git_malformed_proposal

The Git ref proposal is malformed.

**Fix:** Retry with a current stock Git client and one explicit branch refspec.

## git_multi_ref_unsupported

A push containing a protected ref must update exactly one ref.

**Fix:** Push main separately with git push origin HEAD:main.

## git_non_fast_forward

The push would replace remote history.

**Fix:** Run git fetch origin, integrate the remote branch, then retry without --force.

## git_protected_ref_delete

This ref cannot be deleted with this credential.

**Fix:** Keep main intact and push your changes with git push origin HEAD:drafts/workspace when that target is allowed.

## git_ref_not_allowed

This credential cannot push this ref.

**Fix:** For a human authoring credential, save the revision with git push origin HEAD:drafts/workspace; human push targets are main and drafts/workspace.

## git_repository_denied

Access to the Workspace repository is disabled.

**Fix:** Ask a Workspace administrator to restore repository access using the correlation ID.

## git_repository_purged

The Workspace repository has been permanently deleted.

**Fix:** Use an existing Workspace repository or create a new Workspace; this repository cannot be restored.

## git_repository_unavailable

The Workspace repository is temporarily unavailable.

**Fix:** Wait for Workspace maintenance to finish, then retry; contact support with the correlation ID if it persists.

## git_reserved_ref

The ref belongs to a server-owned namespace.

**Fix:** Remove refs/limilake/ from your push refspec and push only authoring refs.

## git_size_limit

The push exceeds the server's size or ref-count limit.

**Fix:** Remove large generated files from the commits being pushed or split the ref updates into smaller pushes.

## layout_not_directory

A source area is not a directory.

**Fix:** Replace the apps, functions or queries entry with a directory containing its resources.

## path_reserved

A source path uses a reserved directory.

**Fix:** Move authored source outside .git and .limilake and update its references.

## path_symlink_escape

A source path escapes the Workspace through a symlink.

**Fix:** Replace the escaping symlink with a file contained inside the Workspace.

## path_traversal

A source name is not a safe path component.

**Fix:** Rename the resource to a single directory name without path traversal.

## query_schema_contract

The Query schema violates the source contract.

**Fix:** Correct the schema's query slug, unique parameter and column names, and supported keys using the Query schema contract.

## query_schema_invalid

The Query schema is unreadable or malformed.

**Fix:** Replace the Query schema with a regular valid JSON schema file from authorized introspection.

## query_schema_missing

The Query's reviewed schema is missing.

**Fix:** Refresh the Query schema through authorized introspection and commit the matching .schema.json file.

## query_schema_orphaned

The Query schema has no matching SQL file.

**Fix:** Commit the matching .sql file or remove the orphaned schema.

## query_schema_version_unsupported

The Query schema version is unsupported.

**Fix:** Refresh and commit a Query schema with supported schemaVersion 1.

## query_slug_invalid

The Query filename is invalid.

**Fix:** Rename the Query SQL and schema files to the same lowercase slug.

## query_sql_invalid

The Query SQL source is unreadable or invalid.

**Fix:** Commit the Query SQL as a contained regular UTF-8 file.

## query_stray_entry

The Queries area contains an unsupported entry.

**Fix:** Keep only named .sql and matching .schema.json files in queries/.

## resource_identity_kind_reuse

The resource UUID already belongs to a different resource kind.

**Fix:** Restore this resource's own durable UUID; assign a new UUID only if you are creating a new resource.

## source_admission_rejected

The candidate does not satisfy source admission.

**Fix:** Run limilake generate --check, fix its diagnostics, then retry; give unresolved cases and the correlation ID to support.

## workspace_contract_not_activated

Contract-v2 admission has not been activated.

**Fix:** Ask platform support to complete the governed Contract-v2 activation using the correlation ID; keep the current Contract version.

## workspace_contract_regression

The candidate lowers the accepted Workspace Contract version.

**Fix:** Restore the accepted Contract version in limilake.toml and keep the existing durable resource IDs.

---

<!-- querying-data.md -->

---
title: Querying data
slug: querying-data
summary: Lakehouses, schemas, and reading data with SQL through the Lake Query API.
---

# Querying data

Data lives in **lakehouses** — server-side data containers, one per logical dataset within a workspace. A lakehouse holds **schemas** (commonly `bronze` / `silver` / `gold`, or custom), and schemas hold **tables** and **files**.

Tables use **DuckLake**, DuckDB's native lakehouse format: the catalog lives in PostgreSQL and the data is Parquet in object storage. The catalog is the single source of truth — there is no repo `.lakehouse.yaml` to drift out of date.

## Discover

```
limilake lakehouse list
limilake lakehouse schema my-lakehouse
limilake table list --lakehouse my-lakehouse
limilake lakehouse explain my-lakehouse
```

`explain` blends the live schema with this concept doc — the `kubectl explain` pattern.

`table list --lakehouse sales` accepts a canonical slug, qualified ref such as
`finance.sales`, or UUID, compared case-insensitively. It filters all readable discovery rows locally;
display names and partial matches are not selectors. If a slug exists in several
Workspaces, use its qualified ref or add `--workspace finance`. Omitting filters
lists all discoverable tables, ignoring environment and linked-checkout defaults.
No matching rows is a successful empty result; table output names the filters; an incomplete or failed discovery returns an error.

## Read

Ad-hoc SQL runs through the HTTP Lake Query API (read-only, bounded). No local
data engine is required:

```
limilake query "SELECT customer, total FROM gold.sales ORDER BY total DESC LIMIT 20" \
  --lakehouse my-lakehouse

limilake table read gold.sales --lakehouse my-lakehouse --limit 50
```

Attach more than one lakehouse with repeated `--lakehouse` flags; reference each by its catalog alias in the SQL.

## Download files

Choose an explicit destination and keep the format flag before `file`:

```bash
limilake file download analytics 11111111-1111-4111-8111-111111111111 --output-file report.csv
limilake --result-schema v1 -o json file download analytics 11111111-1111-4111-8111-111111111111 --output-file report.csv
```

With `--output-file` and `--result-schema v1`, JSON and YAML report
`schema_version:1`, `action:file.download` and a `result` containing `file_id`,
`output_file`, and `size_bytes` after a complete transfer. Legacy result selection
retains the prose acknowledgement with a stderr deprecation. Output paths expand
`~`; `LIMILAKE_OUTPUT` always selects format, never a destination. The signed download URL is never printed.
A failed transfer leaves the existing destination intact. A destination named
`-` is a literal file, not stdout.

Legacy `-o PATH` and `--output PATH` after `download` or `get` still select a
destination, including files named `json` and a quoted `~` kept literally. They emit a deprecation on stderr
and retain their meaning for two subsequent stable releases and at least 30
days, until an announced breaking release. Explicit empty legacy destinations
still request raw stdout and warn; they conflict with `--output-file`. Conflicting old/new destinations
fail before any request. Legacy invocations without a destination retain exact
file bytes on stdout, regardless of format; use `--output-file` for structured
download metadata. With `--error-format json`, failures in metadata mode return
a stable error object on stderr and on JSON/YAML stdout; a raw stdout download
keeps its errors on stderr. All retained `file get` and `lake file` routes follow these
same rules.

## Provisioning

Lakehouses are platform objects, created via the API, never authored as files:

```
limilake lakehouse create analytics --workspace my-workspace
```

## Read-only by design

Lake queries are read-only and capped at `--max-rows`. The real enforcement is server-side (scoped storage credentials, short-lived database roles, and token scopes), so a query can only touch the data your mounts and grants allow.

---

<!-- reporting-problems.md -->

---
title: Report a platform problem
slug: reporting-problems
summary: Send a problem report with optional Markdown details to LimiLake support from the CLI.
---

# Report a platform problem

Use `limilake report` when a LimiLake workflow fails, behaves unexpectedly, or
is hard to understand. The command submits a subject, with optional Markdown
details, to LimiLake support and returns the created issue identifier and URL.

```bash
limilake report "Git push selected the wrong Tenant"

limilake report "Git push selected the wrong Tenant" \
  --body "The credential helper used another Tenant after the shared profile changed."
```

For a multiline description, keep the Markdown in a file or pipe it through
standard input:

```bash
limilake report "Function invocation result was not visible" --body @report.md

printf '%s\n' \
  '## Reproduction' \
  '' \
  '1. Invoke the Function.' \
  '2. Watch the returned Run ID.' |
  limilake --output json report "Function Run was hard to monitor" --body -
```

`--body` is optional and accepts literal Markdown, `@file`, or `-` for standard
input. Omitting it submits only the subject and does not read standard input.
The subject is limited to 200 characters and an explicit body to 20,000 UTF-8
bytes. On a host, `--profile <name>` explicitly selects that stored profile even
when `LIMILAKE_TOKEN` or `LIMILAKE_TOKEN_FILE` is set. Without `--profile`,
ambient environment credentials retain their normal precedence. A stale
checkout Tenant binding does not prevent reporting; the platform still
authenticates the selected credential live and derives the Tenant and reporter
from it. Released CLI requests also carry `User-Agent: limilake/<version>`; the
created support issue records that strictly parsed release identity to make
version-specific friction easier to reproduce.

Managed sandbox credentials cannot submit reports in this first version: the
endpoint rejects sandbox/on-behalf-of authority. Use the CLI from an
authenticated host profile, or ask a human operator to submit the report.

The command does not collect diagnostics automatically. Include the smallest
reproduction that explains the friction, such as the command spelling, safe
error text, expected behavior, and what happened instead. Do not include:

- passwords, access tokens, API keys, cookies, connection strings, or other
  credentials;
- unnecessary personal or customer data;
- environment dumps, complete logs, command history, source archives, or Git
  diffs; or
- any other material that is not needed to understand the problem.

There is intentionally no report list, show, status, update, or delete command.
The returned receipt only confirms that LimiLake support accepted the report.