Docs
Kiwi Fabric
Version Current

CLI reference

Kiwi Fabric CLI reference

Every kiwi fabric command with its options.

Fabric Current 16 min read Updated

The Kiwi Fabric command-line interface runs as kiwi fabric <command> inside the Kiwi shell. Commands are grouped by the object they manage. Options marked (required) must be supplied; everything else is optional.

Options shared by many commands#

These options are accepted by most commands. --url and --key override the saved server URL and API key for a single call.

  • --url: Server URL override.
  • --key: API key override.
  • --json, -j: Output as JSON.

AI assistants and generation#

kiwi fabric ai-config-default — Mark an AI config as the server-wide default.

  • --name, -n (required): Config name.

kiwi fabric ai-config-disable — Soft-disable an AI config (excluded from generation calls).

  • --name, -n (required): Config name.

kiwi fabric ai-config-enable — Re-enable a previously disabled AI config.

  • --name, -n (required): Config name.

kiwi fabric ai-config-remove — Delete an AI/LLM configuration.

  • --name, -n (required): Config name.

kiwi fabric ai-config-set — Create or replace an AI/LLM configuration.

  • --name, -n (required): Config name (used as the ID).
  • --provider, -p (required): Provider name, e.g. OpenAI | AzureOpenAI | Anthropic.
  • --model, -m (required): Model ID, e.g. gpt-4o | claude-3-5-sonnet.
  • --api-key: Provider API key. Pass the masked hint to preserve the existing stored key.
  • --base-url: Custom base URL (required for Azure OpenAI or self-hosted models).
  • --deployment: Deployment name (Azure OpenAI).
  • --max-tokens: Maximum tokens to generate.
  • --temperature: Sampling temperature (0.0 – 2.0).

kiwi fabric ai-config-test — Ping the configured LLM provider and verify stored credentials.

  • --name, -n (required): Config name.

kiwi fabric ai-configs — List registered AI/LLM configurations.

kiwi fabric ai-saga — Generate a saga request JSON from a natural-language prompt.

  • --prompt, -p: Natural-language description of the transaction.
  • --file, -f: Path to a text file containing the prompt.
  • --config, -c (required): AI config ID to use for generation.

kiwi fabric ai-sql — Generate cross-source SQL from a natural-language prompt.

  • --prompt, -p: Natural-language description of the query.
  • --file, -f: Path to a text file containing the prompt.
  • --config, -c (required): AI config ID to use for generation.
  • --run, -R: Immediately execute the generated SQL and display results.

API keys#

kiwi fabric key-add — Create a new API key for a user. The raw key is shown exactly once — save it immediately.

  • --user, -u (required): User ID to create the key for.
  • --name, -n (required): Descriptive name for the key.
  • --expires: Expiry date in ISO 8601 format, e.g. 2027-01-01. Omit for no expiry.

kiwi fabric key-revoke — Permanently revoke an API key by its ID.

  • --id, -i (required): Key ID to revoke.

kiwi fabric keys — List API keys for a user (raw keys are never shown).

  • --user, -u (required): User ID whose keys to list.

Authentication and setup#

kiwi fabric auth-setup — One-time bootstrap: creates the first admin user and prints the initial API key. Fails if any user already exists.

  • --user, -u (required): Admin user ID to create.
  • --password, -p (required): Initial password.

Capabilities (tables)#

kiwi fabric cap — Show details for a single capability.

  • --table, -t (required): Capability table name.

kiwi fabric cap-add — Create a new capability from a JSON definition.

  • --def: Capability definition as an inline JSON string.
  • --file, -f: Path to a JSON file containing the capability definition.

kiwi fabric cap-exec — Directly execute a stored-procedure capability, bypassing the query engine.

  • --table, -t (required): Capability table name.
  • --param: Parameters as comma-separated key=value pairs, e.g. --param orderId=42,customerId=7

kiwi fabric cap-remove — Delete or deactivate a capability.

  • --table, -t (required): Capability table name.

kiwi fabric cap-update — Create or replace a capability from a JSON definition.

  • --table, -t (required): Capability table name to update.
  • --def: Capability definition as an inline JSON string.
  • --file, -f: Path to a JSON file containing the capability definition.

kiwi fabric caps — List registered capabilities.

  • --source: Filter by datasource name.
  • --table: Filter by table name (partial match).
  • --page: Page number.
  • --page-size: Results per page.

Column masks (column-level security)#

kiwi fabric column-mask-add — Add a column mask to a role. Strategy: deny | mask_null | mask_redact | mask_partial.

  • --role, -r (required): Role ID.
  • --table, -t (required): Table name.
  • --column, -c (required): Column name to mask.
  • --strategy, -s: Masking strategy: deny (default) | mask_null | mask_redact | mask_partial.
  • --replacement: mask_redact: full replacement text (default "**"). mask_partial: single mask character (default '').
  • --keep-prefix: mask_partial only: leading characters left unmasked.
  • --keep-suffix: mask_partial only: trailing characters left unmasked.

kiwi fabric column-mask-remove — Delete a column mask from a role.

  • --role, -r (required): Role ID.
  • --id, -i (required): Column mask ID.

kiwi fabric column-mask-update — Update an existing column mask. Strategy: deny | mask_null | mask_redact | mask_partial.

  • --role, -r (required): Role ID.
  • --id, -i (required): Column mask ID.
  • --table, -t (required): Table name.
  • --column, -c (required): Column name to mask.
  • --strategy, -s: Masking strategy: deny (default) | mask_null | mask_redact | mask_partial.
  • --replacement: mask_redact: full replacement text (default "**"). mask_partial: single mask character (default '').
  • --keep-prefix: mask_partial only: leading characters left unmasked.
  • --keep-suffix: mask_partial only: trailing characters left unmasked.

kiwi fabric column-masks — List column masks (CLS) defined for a role.

  • --role, -r (required): Role ID.

Data sources#

kiwi fabric source — Show details for a single datasource.

  • --name, -n (required): Datasource name.

kiwi fabric source-add — Register a new datasource.

  • --name, -n (required): Unique datasource name.
  • --conn, -c (required): Connection string template.
  • --type: Type: Rdbms | Rest | Soap | NoSql | File | Cloud | VectorDb
  • --subtype: Sub-type, e.g. SqlServer | Postgres | MongoDB | Qdrant | CSV (see docs).
  • --desc: Optional description.
  • --username: Database username.
  • --password, -p: Database password.

kiwi fabric source-disable — Deactivate a datasource (capabilities remain registered but excluded from queries).

  • --name, -n (required): Datasource name.

kiwi fabric source-enable — Activate a datasource so its capabilities become queryable.

  • --name, -n (required): Datasource name.

kiwi fabric source-qdrant-collection — Show schema info for a single Qdrant collection.

  • --name, -n (required): Datasource name.
  • --collection, -c (required): Collection name.

kiwi fabric source-qdrant-collections — List Qdrant collection names for a VectorDb datasource.

  • --name, -n (required): Datasource name.

kiwi fabric source-qdrant-test — Ping a Qdrant VectorDb datasource and verify credentials.

  • --name, -n (required): Datasource name.

kiwi fabric source-remove — Delete a user-created datasource and all its capabilities.

  • --name, -n (required): Datasource name.

kiwi fabric source-schema — Fetch the live table/column schema from the underlying database.

  • --name, -n (required): Datasource name.

kiwi fabric source-update — Update an existing datasource's connection details.

  • --name, -n (required): Datasource name.
  • --conn, -c (required): New connection string template.
  • --desc: New description (omit to keep existing).
  • --username: New username (omit to keep existing).
  • --password, -p: New password (omit to keep existing).

kiwi fabric sources — List registered datasources.

  • --type: Filter by type: Rdbms | Rest | Soap | NoSql | File | Cloud | VectorDb
  • --page: Page number.
  • --page-size: Results per page.

Export and import#

kiwi fabric export — Export selected object types to an encrypted JSON file. Requires superadmin.

  • --types, -t: Comma-separated object types to export. Choices: datasources, capabilities,
  • --passphrase, -p (required): Encryption passphrase used to protect the export file.
  • --out, -o (required): Output file path, e.g. ./backup.json.

kiwi fabric import — Import from an encrypted JSON file produced by 'kiwi fabric export'. Requires superadmin.

  • --file, -f (required): Path to the export JSON file.
  • --passphrase, -p (required): Passphrase used when the export was created.
  • --conflict, -c: Conflict strategy: skip (default) | overwrite.

Files#

kiwi fabric file-remove — Delete an uploaded file from the server's storage and metadata registry.

  • --id, -i (required): File ID (GUID) to delete.

kiwi fabric file-upload — Upload a local file to the server's managed storage.

  • --path, -p (required): Path to the local file to upload.
  • --format: Format hint: Csv | Tsv | Json | Parquet | Excel | Delta | Iceberg. Omit to infer from extension.

kiwi fabric files — List files uploaded to the server's managed storage.

Groups#

kiwi fabric group-add — Create a new group.

  • --name, -n (required): Group name.
  • --desc, -d: Optional description.

kiwi fabric group-member-add — Add a user to a group.

  • --id, -i (required): Group ID.
  • --user, -u (required): User ID to add.

kiwi fabric group-member-remove — Remove a user from a group.

  • --id, -i (required): Group ID.
  • --user, -u (required): User ID to remove.

kiwi fabric group-members — List members (user IDs) of a group.

  • --id, -i (required): Group ID.

kiwi fabric group-remove — Soft-delete (deactivate) a group.

  • --id, -i (required): Group ID.

kiwi fabric group-role-assign — Assign a role to a group; all group members inherit it.

  • --id, -i (required): Group ID.
  • --role, -r (required): Role ID to assign.

kiwi fabric group-role-revoke — Revoke a role from a group.

  • --id, -i (required): Group ID.
  • --role, -r (required): Role ID to revoke.

kiwi fabric group-roles — List roles assigned to a group.

  • --id, -i (required): Group ID.

kiwi fabric groups — List all active groups.

Kerberos#

kiwi fabric kerberos-remove — Unlink the Kerberos principal from a user (disables SSO for that account).

  • --user, -u (required): User ID.

kiwi fabric kerberos-set — Link a Windows/AD Kerberos principal to a user account, enabling SSO login.

Lineage#

kiwi fabric lineage — Show the full cross-source dependency graph for all virtual tables and capabilities.

  • --verbose, -V: Show DependsOn and UsedBy edges for every node.

kiwi fabric lineage-deps — Show all tables that a given virtual table transitively depends on.

  • --name, -n (required): Virtual table name to trace.

kiwi fabric lineage-impact — Show all virtual tables that would break if a given table were changed or deleted.

  • --name, -n (required): Table or virtual table name to analyse.

Permissions#

kiwi fabric perm-add — Add a permission to a role. Use '*' for wildcard operation or resource.

  • --role, -r (required): Role ID.
  • --operation, -o (required): Permission operation, e.g. read | write | execute | * (all).
  • --resource (required): Resource name or pattern, e.g. datasource:sales | capability:* | *.
  • --effect: Effect: ALLOW (default) | DENY.

kiwi fabric perm-remove — Delete a permission from a role.

  • --role, -r (required): Role ID.
  • --id, -i (required): Permission ID.

Queries#

kiwi fabric query — Execute a cross-source SQL query.

  • --sql, -s: SQL statement to execute.
  • --file, -f: Path to a .sql file to execute.
  • --param: Named parameters as comma-separated key=value pairs, e.g. --param minAge=18,city=London
  • --verbose, -V: Show per-source fetch breakdown after the result table.

Resource guards#

kiwi fabric resource-guards-get — Show the current global resource-guard settings (query timeout, max result rows, concurrency cap, REST rate limit).

kiwi fabric resource-guards-set — Update the global resource-guard settings. Requires superadmin. .

  • --timeout, -t (required): Query timeout in seconds.
  • --max-rows, -r (required): Maximum rows a single query result (or a single handler fetch) may return before being rejected.
  • --max-concurrent, -c (required): Maximum concurrently-executing queries across REST, Postgres wire, and Arrow Flight.
  • --rate-limit (required): REST requests allowed per minute (requires a server restart to take effect).

Roles#

kiwi fabric role-add — Create a new role.

  • --name, -n (required): Role name.
  • --desc, -d: Optional description.

kiwi fabric role-perms — List all permissions defined for a role.

  • --role, -r (required): Role ID.

kiwi fabric role-remove — Soft-delete (deactivate) a role.

  • --id, -i (required): Role ID.

kiwi fabric roles — List all active roles.

Row filters (row-level security)#

kiwi fabric row-filter-add — Add a row filter to a role. filterJson uses the saga filter predicate grammar, plus {"$user":"id"|"groups"}.

  • --role, -r (required): Role ID.
  • --table, -t (required): Table name to restrict.
  • --filter, -f (required): Filter predicate JSON, e.g. {"type":"eq","column":"tenant_id","value":{"$user":"id"}}.

kiwi fabric row-filter-remove — Delete a row filter from a role.

  • --role, -r (required): Role ID.
  • --id, -i (required): Row filter ID.

kiwi fabric row-filter-update — Update an existing row filter's table/predicate.

  • --role, -r (required): Role ID.
  • --id, -i (required): Row filter ID.
  • --table, -t (required): Table name to restrict.
  • --filter, -f (required): Filter predicate JSON, e.g. {"type":"eq","column":"tenant_id","value":{"$user":"id"}}.

kiwi fabric row-filters — List row filters (RLS) defined for a role.

  • --role, -r (required): Role ID.

Sagas#

kiwi fabric saga-gaps — Show compensation gap report for a saga.

  • --id, -i (required): Saga ID.

kiwi fabric saga-list — List saga executions with optional state filter.

  • --state: Filter by state: Pending | Running | Completed | Failed | Compensating | Compensated | CompensationFailed | DeadLettered
  • --page: Page number.
  • --page-size: Results per page.

kiwi fabric saga-run — Execute a distributed saga request.

  • --body, -b: Saga request as an inline JSON string.
  • --file, -f: Path to a JSON file containing the SagaRequest.

kiwi fabric saga-status — Get the current state of a saga by ID.

  • --id, -i (required): Saga ID.

Sign in and session#

kiwi fabric connect — Save the Kiwi Fabric server URL (and optional API key) for all subsequent commands.

  • --url, -u (required): Kiwi Fabric server base URL, e.g. https://localhost:5000
  • --key, -k: Long-lived API key. Omit to authenticate interactively with 'kiwi fabric login'.

kiwi fabric login — Authenticate and cache a session token for subsequent commands.

  • --user, -u: User ID.
  • --password, -p: Password.
  • --kerberos, -K: Authenticate via Kerberos/SPNEGO (Windows Negotiate). No credentials required.

kiwi fabric logout — Clear the cached session token.

kiwi fabric password-change — Change your own password. Requires your current password.

  • --current-password (required): Your current password.
  • --new-password (required): The new password to set.

kiwi fabric whoami — Show the current session's user ID and superadmin status.

Telemetry#

kiwi fabric telemetry — Show an aggregated summary of query/saga activity (counts, failure rate, average latency).

  • --from: Start of time window (ISO 8601). Omit for all-time.
  • --to: End of time window (ISO 8601). Omit for now.

kiwi fabric telemetry-latency — Show a time-series of average and p95 latency, bucketed by hour or day.

  • --from: Start of time window (ISO 8601).
  • --to: End of time window (ISO 8601).
  • --bucket: Bucket size: hour | day.

kiwi fabric telemetry-log — Browse the paginated request log with optional filters.

  • --type: Filter by type: Query | Saga.
  • --status: Filter by status: Success | Failed | Compensated | DeadLettered.
  • --user: Filter to a specific user ID.
  • --from: Start of time window (ISO 8601).
  • --to: End of time window (ISO 8601).
  • --page: Page number.
  • --page-size: Results per page (max 100).

kiwi fabric telemetry-request — Show full detail for a single request-log entry, including per-source breakdown.

  • --id, -i (required): Request ID (GUID).

kiwi fabric telemetry-users — Show per-user request counts, failure rates, and average latency.

  • --from: Start of time window (ISO 8601).
  • --to: End of time window (ISO 8601).
  • --user: Filter to a single user ID.
  • --page: Page number.
  • --page-size: Results per page.

Templates#

kiwi fabric template-add — Create a new saved saga template from a JSON definition.

  • --def: Full CreateSavedSagaRequest as an inline JSON string.
  • --file, -f: Path to a JSON file containing the CreateSavedSagaRequest.

kiwi fabric template-get — Show a single saved saga template's stored definition.

  • --name, -n (required): Template name.

kiwi fabric template-remove — Delete a saved saga template.

  • --name, -n (required): Template name.

kiwi fabric template-run — Execute a saved saga template with parameter values.

  • --name, -n (required): Template name.
  • --param: Template parameters as comma-separated key=value pairs, e.g. --param orderId=42,customerId=7

kiwi fabric template-set — Create or replace a saved saga template.

  • --name, -n (required): Template name to create or replace.
  • --def: Full CreateSavedSagaRequest as an inline JSON string.
  • --file, -f: Path to a JSON file containing the CreateSavedSagaRequest.

kiwi fabric templates — List saved saga templates.

Users#

kiwi fabric superadmin-grant — Grant wildcard (ALLOW * ON *) superadmin permissions to a user. Idempotent.

  • --user, -u (required): User ID to promote.

kiwi fabric user-activate — Reactivate a previously deactivated user account.

  • --user, -u (required): User ID to reactivate.

kiwi fabric user-add — Create a new user account.

  • --user, -u (required): New user ID.
  • --password, -p (required): Initial password.
  • --domain: Optional Windows/AD domain username (for Kerberos SSO).

kiwi fabric user-groups — List the groups a user belongs to.

  • --user, -u (required): User ID.

kiwi fabric user-remove — Deactivate a user account (soft delete — they can no longer authenticate).

  • --user, -u (required): User ID to deactivate.

kiwi fabric user-reset-password — Admin password reset for any user. Does not require their current password.

  • --user, -u (required): User ID whose password to reset.
  • --password, -p (required): The new password to set.

kiwi fabric user-role-assign — Directly assign a role to a user.

  • --user, -u (required): User ID.
  • --role, -r (required): Role ID.

kiwi fabric user-role-revoke — Revoke a directly-assigned role from a user.

  • --user, -u (required): User ID.
  • --role, -r (required): Role ID.

kiwi fabric user-roles — List roles directly assigned to a user (not inherited via groups).

  • --user, -u (required): User ID.

kiwi fabric users — List all registered users.

Versioning#

kiwi fabric version-batch-summaries — Batch-fetch the latest version summary for multiple entity IDs of the same type.

  • --type, -t (required): Entity type.
  • --entities, -e (required): Comma-separated entity IDs, e.g. --entities Orders,Customers,Invoices

kiwi fabric version-diff — Show a field-level diff between two versions of an entity.

  • --type, -t (required): Entity type.
  • --entity, -e (required): Entity name / ID.
  • --from (required): Source version number.
  • --to (required): Target version number.

kiwi fabric version-get — Retrieve a specific version including its full snapshot JSON.

  • --type, -t (required): Entity type.
  • --entity, -e (required): Entity name / ID.
  • --num, -n (required): Version number.

kiwi fabric version-publish — Promote a draft version to 'published' status.

  • --type, -t (required): Entity type.
  • --entity, -e (required): Entity name / ID.
  • --num, -n: Version number to publish. Omit to publish the latest draft.

kiwi fabric versions — List all versions of an entity (newest first).

  • --type, -t (required): Entity type: data-source | capability | virtual-table | saga-template | ai-assistant
  • --entity, -e (required): Entity name / ID.

Virtual tables#

kiwi fabric vtable — Show details for a single virtual table.

  • --name, -n (required): Virtual table name.

kiwi fabric vtable-add — Create a new virtual table from a cross-source SQL query.

  • --name, -n (required): Virtual table name.
  • --sql, -s: SQL query string.
  • --file, -f: Path to a .sql file.
  • --desc: Optional description.

kiwi fabric vtable-remove — Delete a virtual table.

  • --name, -n (required): Virtual table name.

kiwi fabric vtable-set — Create or replace a virtual table.

  • --name, -n (required): Virtual table name.
  • --sql, -s: SQL query string.
  • --file, -f: Path to a .sql file.
  • --desc: Optional description.

kiwi fabric vtables — List all virtual tables.