Kiwi Flow CLI reference

The Kiwi Flow command-line interface runs as kiwi flow <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.
• --id, -i: Key ID to revoke.

AI assistants and generation#

kiwi flow ai-assistant-default — Mark an AI assistant as the server-wide default.

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

kiwi flow ai-assistant-disable — Soft-disable an AI assistant (excluded from Generate/Enhance calls).

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

kiwi flow ai-assistant-enable — Re-enable a previously disabled AI assistant.

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

kiwi flow ai-assistant-remove — Delete an AI assistant configuration.

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

kiwi flow ai-assistant-set — Create or replace an AI assistant configuration.

• --name, -n (required): Assistant 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-sonnet-5-5.
• --api-key: Provider API key. Omit to preserve the existing stored key.
• --endpoint: Custom endpoint URL (required for Azure OpenAI or self-hosted models).
• --deployment: Deployment name (Azure OpenAI).
• --region: Region (some cloud providers).
• --max-retries: Maximum retries on a transient failure.
• --temperature: Sampling temperature (0.0 - 2.0).
• --max-tokens: Maximum tokens to generate.

kiwi flow ai-assistant-test — Ping the configured AI provider and verify stored credentials.

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

kiwi flow ai-assistants — List registered AI assistant configurations.

• --json, -j: Output as JSON.

kiwi flow ai-enhance — Enhance an existing, already-saved workflow from a natural-language instruction.

• --workflow-id, -w (required): Workflow ID to enhance.
• --prompt, -p: Natural-language description of the change.
• --file, -f: Path to a text file containing the prompt.
• --assistant, -a: AI assistant ID to use. Omit to use the server default.
• --out, -o: Save the enhanced workflow JSON to this file instead of printing it.

kiwi flow ai-generate — Generate a brand-new workflow from a natural-language prompt.

• --prompt, -p: Natural-language description of the workflow.
• --file, -f: Path to a text file containing the prompt.
• --assistant, -a: AI assistant ID to use. Omit to use the server default.
• --out, -o: Save the generated workflow JSON to this file instead of printing it.

API keys#

kiwi flow 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 flow key-revoke — Permanently revoke an API key by its ID.

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

• --user, -u (required): User ID whose keys to list.
• --json, -j: Output as JSON.

Activity catalogue#

kiwi flow catalogue — Dump the full activity catalogue (every supported activity type, its inputs/outputs).

Approval and external tasks#

kiwi flow task-approve — Approve a pending approval task, resuming its run.

• --comment, -c: Optional comment recorded with the resolution.

kiwi flow task-reject — Reject a pending approval task, resuming its run down the rejection path.

• --comment, -c: Optional comment recorded with the resolution.

kiwi flow tasks-mine — List approval tasks assigned to you (or your roles/groups).

• --status, -s: Filter by status, e.g. Pending | Approved | Rejected. Omit for all.
• --json, -j: Output as JSON.

Audit#

kiwi flow audit — List audit log entries, with optional filters.

• --user, -u: Filter by the user who performed the action.
• --operation, -o: Filter by operation, e.g. admin.users.create.
• --resource-type, -r: Filter by resource type, e.g. user | workflow | connection.
• --from: Only entries at or after this UTC timestamp (ISO 8601).
• --to: Only entries at or before this UTC timestamp (ISO 8601).
• --limit, -l: Maximum entries to return.
• --json, -j: Output as JSON.

Authentication and setup#

kiwi flow 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.
• --email, -e (required): Admin email address.

Connections#

kiwi flow connection-create — Save a new connection. --fields-json holds the activity type's own connection fields.

• --type, -t (required): Activity typeString this connection is for, e.g. sql_database_connection.
• --name, -n (required): Connection name.
• --fields-json, -f (required): Connection fields as a JSON object, matching the activity type's own catalogue inputs.
• --shared: Save as a shared connection instead of a personal one.

kiwi flow connection-delete — Delete a connection.

• --shared: Delete a shared connection instead of a personal one.

kiwi flow connection-get — Retrieve a connection's full detail, including its (secret-masked) fields.

• --shared: Look up a shared connection instead of one of your personal ones.
• --json, -j: Output as JSON.

kiwi flow connection-set-default — Mark a connection as the default for its activity type.

• --shared: A shared connection instead of a personal one.

kiwi flow connection-test — Test connection fields (or an already-saved connection by ID) without necessarily saving them.

• --type, -t (required): Activity typeString this connection is for.
• --fields-json, -f: Connection fields as a JSON object, to test ad hoc.
• --shared: The connection ID (with --id) refers to a shared connection.

kiwi flow connection-update — Update an existing connection's name/fields.

• --type, -t (required): Activity typeString this connection is for.
• --name, -n (required): Connection name.
• --fields-json, -f (required): Connection fields as a JSON object.
• --shared: Update a shared connection instead of a personal one.

kiwi flow connections — List your saved connections, or shared ones with --shared.

• --shared: List shared connections instead of your personal ones.
• --type, -t: Filter by activity typeString, e.g. sql_database_connection.
• --json, -j: Output as JSON.

External tasks#

kiwi flow external-task-complete — Complete an external task by ID (authenticated), resuming its run.

• --data-json, -d: Result data as a JSON value, e.g. {"approved":true}.

kiwi flow external-task-complete-callback — Complete an external task via its one-time callback token — no login required, for use by external systems invoking the callback URL directly.

• --token, -t (required): Callback token (from the task's CallbackUrl).
• --data-json, -d: Result data as a JSON value.

kiwi flow external-task-fail — Fail an external task by ID (authenticated), resuming its run down the failure path.

• --error, -e: Failure reason recorded on the task.

kiwi flow external-task-fail-callback — Fail an external task via its one-time callback token — no login required, for use by external systems invoking the callback URL directly.

• --token, -t (required): Callback token (from the task's FailUrl).
• --error, -e: Failure reason recorded on the task.

kiwi flow external-tasks-for-run — List external tasks belonging to a specific run (ops view — includes callback URLs).

• --run-id, -r (required): Run ID.
• --json, -j: Output as JSON.

kiwi flow external-tasks-mine — List external tasks assigned to you (or your roles/groups).

• --status, -s: Filter by status, e.g. Pending | Completed | Failed. Omit for all.
• --json, -j: Output as JSON.

Groups#

kiwi flow group-add — Create a new group.

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

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

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

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

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

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

kiwi flow group-remove — Delete a group.

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

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

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

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

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

kiwi flow groups — List all groups.

• --json, -j: Output as JSON.

Licensing#

kiwi flow license-activate — Activate the server with a license activation key.

• --activation-key, -k (required): Activation key issued by Kiwi Licensing.

kiwi flow license-status — Show the current license status.

OAuth2#

kiwi flow oauth-authorize-url — Get the browser URL to open to complete an OAuth2 connect flow for a saved Google/Microsoft connection.

• --provider, -p (required): Provider: google | microsoft.
• --connection-id, -c (required): ID of the google_oauth2/microsoft_oauth2 connection to authorize.
• --scope, -s (required): OAuth scope(s) to request, space-separated as the provider expects.

Permissions#

kiwi flow 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. admin.users | admin.roles | * (all).
• --resource (required): Resource name or pattern, e.g. workflow:* | connection:* | *.
• --effect: Effect: ALLOW (default) | DENY.

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

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

Resource guards#

kiwi flow resource-guards-get — Show the current global resource-guard settings (run timeout, max output size, concurrency cap, REST rate limit).

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

• --timeout, -t (required): Run timeout in seconds.
• --max-output-bytes, -m (required): Maximum output bytes per activity before a run is rejected.
• --max-concurrent-runs, -c (required): Maximum concurrently-executing runs.
• --rate-limit (required): REST requests allowed per minute (requires a server restart to take effect).

Roles#

kiwi flow role-add — Create a new role.

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

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

• --role, -r (required): Role ID.
• --json, -j: Output as JSON.

kiwi flow role-remove — Delete a role.

kiwi flow roles — List all roles.

• --json, -j: Output as JSON.

Runs#

kiwi flow run-cancel — Cancel an in-progress run.

kiwi flow run-get — Retrieve a run's full detail, including inputs/outputs/log.

• --json, -j: Output as JSON.

kiwi flow runs — List runs, optionally filtered to one workflow.

• --workflow-id, -w: Only show runs of this workflow.
• --json, -j: Output as JSON.

Sign in and session#

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

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

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

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

kiwi flow logout — Clear the cached session token.

kiwi flow 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 flow whoami — Show the current session's user ID and superadmin status.

Storage#

kiwi flow storage-area-create — Create a new Area within a Storage.

• --storage-id, -s (required): Storage ID.
• --name, -n (required): Area name.
• --desc, -d: Optional description.

kiwi flow storage-area-delete — Delete an Area from a Storage.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.

kiwi flow storage-area-perms — List per-role permission grants on an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --json, -j: Output as JSON.

kiwi flow storage-area-perms-set — Set (replace) a role's permission grant on an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --role, -r (required): Role ID.
• --operations, -o (required): Comma-separated operations, e.g. read,write,delete. Empty revokes the role entirely.

kiwi flow storage-areas — List Areas within a Storage.

• --storage-id, -s (required): Storage ID.
• --json, -j: Output as JSON.

kiwi flow storage-copy — Copy a file or folder within an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Source relative path.
• --to, -t (required): Destination relative path.
• --overwrite: Overwrite an existing entry at the destination.

kiwi flow storage-create — Create a new governed Storage.

• --name, -n (required): Storage name.
• --root-path, -r (required): Root path on the provider, e.g. a local path or bucket prefix.
• --provider, -p: Provider type, e.g. local | azure_blob | aws_s3 | gcp_storage. Defaults to local.
• --connection-id, -c: Connection ID to use for a cloud provider.
• --desc, -d: Optional description.

kiwi flow storage-delete — Delete a Storage.

kiwi flow storage-file-delete — Delete a file from an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Relative path within the Area.

kiwi flow storage-file-download — Download a file from a path within an Area to a local path.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Source relative path within the Area.
• --out, -o (required): Local destination file path.

kiwi flow storage-file-exists — Check whether a file exists at a path within an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Relative path within the Area.

kiwi flow storage-file-metadata — Show a file's size/timestamps without downloading it.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Relative path within the Area.
• --json, -j: Output as JSON.

kiwi flow storage-file-upload — Upload a local file to a path within an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Destination relative path within the Area.
• --file, -f (required): Local file to upload.
• --overwrite: Overwrite if a file already exists at the destination path.

kiwi flow storage-files — List files/folders at a path within an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p: Relative path to list. Defaults to the Area's root.
• --json, -j: Output as JSON.

kiwi flow storage-folder-create — Create a folder at a path within an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Relative path of the folder to create.

kiwi flow storage-folder-delete — Delete a folder from an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Relative path of the folder to delete.
• --recursive, -r: Delete non-empty folders recursively.

kiwi flow storage-move — Move/rename a file or folder within an Area.

• --storage-id, -s (required): Storage ID.
• --area-id, -a (required): Area ID.
• --path, -p (required): Source relative path.
• --to, -t (required): Destination relative path.
• --overwrite: Overwrite an existing entry at the destination.

kiwi flow storages — List all governed Storages.

• --json, -j: Output as JSON.

System#

kiwi flow system-info — Show the server's app version, data store, and platform info.

• --json, -j: Output as JSON.

Templates#

kiwi flow template-create — Create a new template.

• --kind, -k: Template kind.
• --name, -n (required): Template name.
• --file, -f (required): Path to a file containing the template body.
• --subject, -s: Email subject (email kind).
• --html: The body is HTML.
• --desc, -d: Optional description.

kiwi flow template-delete — Delete a template.

kiwi flow template-get — Retrieve a template's full content.

• --json, -j: Output as JSON.

kiwi flow template-update — Update an existing template's content.

• --name, -n (required): Template name.
• --file, -f (required): Path to a file containing the updated template body.
• --subject, -s: Email subject (email kind).
• --html: The body is HTML.
• --desc, -d: Optional description.

kiwi flow templates — List templates of a given kind (only 'email' exists today).

• --kind, -k: Template kind. Defaults to 'email'.
• --json, -j: Output as JSON.

Triggers#

kiwi flow trigger-create — Create a new trigger.

• --name, -n (required): Trigger name.
• --type, -t (required): Trigger type: trigger_schedule | trigger_email | trigger_webhook | trigger_http_request | trigger_queue.
• --workflow-id, -w (required): Workflow this trigger starts.
• --config-json, -c (required): Trigger-type-specific config as a JSON object, e.g. {"cron":"0 */5 * * * *"} for trigger_schedule.

kiwi flow trigger-delete — Delete a trigger.

kiwi flow trigger-disable — Disable a trigger.

kiwi flow trigger-enable — Enable a trigger.

kiwi flow trigger-get — Retrieve a trigger's full configuration.

• --json, -j: Output as JSON.

kiwi flow trigger-update — Update a trigger's name, target workflow, or config.

• --name, -n (required): Trigger name.
• --workflow-id, -w (required): Workflow this trigger starts.
• --config-json, -c (required): Trigger-type-specific config as a JSON object.

kiwi flow triggers — List triggers, optionally filtered to one target workflow.

• --workflow-id, -w: Only show triggers targeting this workflow.
• --json, -j: Output as JSON.

Users#

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

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

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

• --user, -u (required): New user ID.
• --password, -p (required): Initial password.
• --email, -e (required): User's email address.

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

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

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

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

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

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

kiwi flow 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 flow user-role-assign — Directly assign a role to a user.

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

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

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

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

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

kiwi flow user-set-email — Set a user's email address. Self-service for your own account, admin-only for others.

• --user, -u (required): User ID.
• --email, -e (required): New email address.

kiwi flow users — List all registered users.

• --json, -j: Output as JSON.

Workflows#

kiwi flow workflow-create — Create a new workflow from a definition JSON file.

• --name, -n (required): Workflow name.
• --file, -f (required): Path to the workflow definition JSON file.
• --desc, -d: Optional description.

kiwi flow workflow-delete — Delete a workflow.

kiwi flow workflow-get — Retrieve a workflow's full definition.

• --json, -j: Output as JSON (includes the full definitionJson).

kiwi flow workflow-publish — Publish a workflow's current draft version.

kiwi flow workflow-publishable — List workflows currently eligible to be published.

• --json, -j: Output as JSON.

kiwi flow workflow-run — Execute a workflow and wait for the run to finish.

• --input-json: Workflow input values as a JSON object, e.g. {"orderId":42}.
• --json, -j: Output the run result as JSON.

kiwi flow workflow-share-add — Share a reusable workflow with a user or role.

• --principal-type, -t (required): Principal type: user | role.
• --principal-id, -p (required): User ID or role ID to share with.

kiwi flow workflow-share-remove — Revoke a workflow share.

• --share-id, -s (required): Share ID to revoke.

kiwi flow workflow-shares — List principals a reusable workflow is shared with.

• --json, -j: Output as JSON.

kiwi flow workflow-update — Update an existing workflow's definition.

• --name, -n (required): Workflow name.
• --file, -f (required): Path to the updated definition JSON file.
• --desc, -d: Optional description.

kiwi flow workflow-validate — Validate a workflow definition without saving it — either a local file or an already-stored workflow.

• --file, -f: Path to a definition JSON file to validate ad hoc.

kiwi flow workflow-versions — List all saved versions of a workflow (newest first).

• --json, -j: Output as JSON.

kiwi flow workflows — List all workflows.

• --json, -j: Output as JSON.