Kiwi Distro CLI reference

The Kiwi Distro command-line interface runs as kiwi distro <command> inside the Kiwi shell (or standalone as the Kiwify.Kiwi.Distro.Client.Cli assembly). Commands are grouped by the object they manage. Options marked (required) must be supplied.

Options shared by many commands#

These options are accepted by most commands. Data and method commands can render as a table, highlighted JSON, or plain text for piping.

• --output, -o: Output: message (default) | json | raw.

Client groups#

kiwi distro create-client-group — Create a client group — grant a service/service-group to it once, every member client inherits it.

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

kiwi distro delete-client-group — Delete a client group.

• --client-group-id, -gid (required): Client group id.

kiwi distro get-client-group — Show one client group.

• --client-group-id, -gid (required): Client group id.

kiwi distro get-client-groups — Show which client-groups a client belongs to.

• --client-id, -cid (required): Client id.

kiwi distro list-client-groups — List all client groups.

kiwi distro set-client-group-grants — Set the service/service-group grants every member of this client group inherits.

• --client-group-id, -gid (required): Client group id.
• --services, -s: Comma-separated service ids to grant. Omit/empty to clear.
• --service-groups, -sg: Comma-separated service-group ids to grant. Omit/empty to clear.

kiwi distro set-client-groups — Set which client-groups this client belongs to — each contributes its own grants. Empty clears membership.

• --client-id, -cid (required): Client id.
• --groups, -g: Comma-separated client-group ids. Omit/empty to clear membership.

Clients and client authorization#

kiwi distro delete-client — Delete a client.

• --client-id, -cid (required): Client id.

kiwi distro disable-client — Disable a client.

• --client-id, -cid (required): Client id.

kiwi distro enable-client — Enable a client.

• --client-id, -cid (required): Client id.

kiwi distro get-client — Show a client's details.

• --client-id, -cid (required): Client id.

kiwi distro get-client-allowed-services — Show the services a client may call directly.

• --client-id, -cid (required): Client id.

kiwi distro list-clients — List registered clients, optionally filtered.

• --name, -cn: Name pattern.
• --desc, -cd: Description pattern.
• --roles, -r: Comma-separated roles to filter by.

kiwi distro register-client — Register a new client with the middleware.

• --name, -cn (required): Client name.
• --desc, -cd: Client description.
• --roles, -r (required): Comma-separated roles.
• --auth-token-ttl, -att: Access-token lifetime, e.g. 1H, 30M. Defaults to the middleware's configured value.
• --refresh-token-ttl, -rtt: Refresh-token lifetime, e.g. 24H, 7D. Defaults to 24H.

kiwi distro set-client-allowed-services — Set the services this client may call directly (client-side authorization). Empty clears the grant.

• --client-id, -cid (required): Client id.
• --services, -s: Comma-separated service ids. Omit/empty to clear the grant.

Deployment strategy#

kiwi distro get-deployment-strategy — Show a service's configured deployment strategy.

• --service-id, -sid (required): Service id.

kiwi distro set-deployment-strategy — Set a service's routing strategy: blue/green or canary.

• --service-id, -sid (required): Service id.
• --strategy, -st (required): bluegreen | canary.
• --active, -a (required): Active version — the one live traffic goes to (blue/green), or the fallback (canary).
• --candidate, -c (required): Candidate version — swapped in (blue/green) or given the canary slice.
• --canary-pct, -p: Percent of traffic routed to the candidate (canary only, 0–100).

kiwi distro swap-blue-green — Swap the active and candidate versions of a blue/green service.

• --service-id, -sid (required): Service id.

Feedback#

kiwi distro list-feedback — Read stored feedback with combinable filters.

• --worker-id, -wid: Filter by worker id.
• --request-id, -rid: Filter by request id.
• --service-id, -sid: Filter by service id.
• --worker-ip, -ip: Filter by worker IP address.
• --source-type, -st: MethodRequest | WorkerBackgroundProcess.
• --feedback-type, -ft: Comma-separated FeedbackType names.
• --tags, -tg: Comma-separated worker tags (key:value).
• --page, -p: Page number (default 1).
• --page-size, -ps: Page size (default 50).

Invoking methods#

kiwi distro pick-method-result — Retrieve the result of a previously submitted method.

• --reference-id, -rid (required): Reference id from submit-method.
• --target, -tg: Pick with the same target you submitted: any (default) | all.
• --transport, -tr: http (default) | signalr.

kiwi distro request-bg-process-command — Run a background-process command (start/stop/restart) and wait.

• --service, -s (required): Background service name.
• --command, -c (required): start | stop | restart.
• --target, -tg: any (default) | all | .
• --transport, -tr: http (default) | signalr.

kiwi distro request-method — Invoke a method and wait for the result.

• --method, -m (required): service/method to invoke.
• --params, -p: Params: key='str',key=42,flag=true.
• --params-file, -pf: JSON file with the method parameters.
• --target, -tg: any (default) | all | .
• --ttl, -t: Time-to-live, e.g. 30S / 5M.
• --filters, -f: Filter criteria as JSON array.
• --service-version, -sv: Service version to target.
• --transport, -tr: http (default) | signalr.

kiwi distro submit-bg-process-command — Submit a background-process command (start/stop/restart).

• --service, -s (required): Background service name.
• --command, -c (required): start | stop | restart.
• --target, -tg: any (default) | all | .
• --transport, -tr: http (default) | signalr.

kiwi distro submit-method — Submit a method and get a reference id to pick the result later.

• --method, -m (required): service/method to invoke.
• --params, -p: Params: key='str',key=42,flag=true.
• --params-file, -pf: JSON file with the method parameters.
• --target, -tg: any (default) | all | .
• --ttl, -t: Time-to-live, e.g. 30S / 5M.
• --filters, -f: Filter criteria as JSON array.
• --service-version, -sv: Service version to target.
• --callback-url, -cb: URL the middleware pings when the result is ready.
• --callback-timeout, -cto: Callback timeout, e.g. 30S.
• --transport, -tr: http (default) | signalr.

Middleware#

kiwi distro list-middlewares — List the running middleware instances and their heartbeat status.

Scripts and executors#

kiwi distro authorize-script-version — Authorize a version for execution (admin / super-admin).

• --script-id, -scid (required): Script id.
• --script-version, -sv (required): Version, e.g. 1.2.3.

kiwi distro delete-script — Delete a script and all its versions.

• --script-id, -scid (required): Script id.

kiwi distro disable-script-version — Disable a version so it can no longer execute.

• --script-id, -scid (required): Script id.
• --script-version, -sv (required): Version, e.g. 1.2.3.

kiwi distro execute-script — Run a registered, authorized script by name. You give the service/script and plain name=value params; the internal method and parameter-binding names are handled for you.

• --script, -s (required): service-name/script-name (or just script-name with --service).
• --service: Service name (only if --script is just the script name).
• --params, -p: Parameter values: name=Ajay,count=3,verbose=true (quote values that contain commas; name:= for arrays/objects).
• --params-file, -pf: JSON object of parameter values (merged under --params).
• --env-params, -ep: Extra environment variables: KEY=value,OTHER=value.
• --env-file, -epf: JSON object of extra environment variables (merged under --env-params).
• --script-version, -sv: Pin a version (default: latest authorized).
• --ttl, -t: Request TTL, e.g. 5M.
• --transport, -tr: http (default) | signalr.
• --follow, -fl: Stream the script's console output live, then show the result.

kiwi distro get-script — Show a script definition.

• --script-id, -scid (required): Script id.

kiwi distro list-executors — List the effective executor definitions (built-ins + overrides).

kiwi distro list-script-versions — List a script's versions.

• --script-id, -scid (required): Script id.

kiwi distro list-scripts — List the scripts registered for a service.

• --service-id, -sid (required): Service id.

kiwi distro register-script — Register (or update) a script definition for a service.

• --service-id, -sid (required): Target service id.
• --name, -n (required): Script name (letters, digits, '_' or '-').
• --executor, -e (required): Executor id: python | node | linux_shell | powershell | windows_batch | auto_it | autohotkey | playwright.
• --entry, -ef (required): Entry file, relative to the bundle root.
• --desc, -d: Description.
• --params, -p: Comma-separated specs 'name:binding[:type][:req]', e.g. 'month:named:string:req,verbose:env:boolean'.
• --params-file, -pf: JSON file with a ScriptParameterSpec array (overrides --params).
• --timeout, -t: Default timeout, e.g. 5M.
• --interactive: Require an interactive desktop worker.
• --browser: Require a browser-runtime worker.
• --platforms: Comma-separated platform constraint: windows,linux,macos.

kiwi distro run-script — Run a registered, authorized script (same as execute-script; kept for compatibility).

• --service, -s (required): Service name.
• --script, -n (required): Script name.
• --script-version, -sv: Pin a version (default: latest authorized).
• --params, -p: Parameter values: name=Ajay,count=3 (see execute-script).
• --params-file, -pf: JSON object of parameter values.
• --env-params, -ep: Extra environment variables: KEY=value,OTHER=value.
• --env-file, -ef: JSON object of extra environment variables.
• --ttl, -t: Request TTL, e.g. 5M.
• --transport, -tr: http (default) | signalr.
• --follow, -fl: Stream the script's console output live, then show the result.

kiwi distro script-audit — Show the script audit trail.

• --script-id, -scid: Filter by script id.
• --service-id, -sid: Filter by service id.
• --limit, -l: Max rows (default 100).

kiwi distro upload-script-version — Upload a new version's artifact (single file or .zip). Starts as 'pending'.

• --script-id, -scid (required): Script id.
• --script-version, -sv (required): Version, e.g. 1.2.3.
• --file, -f (required): Artifact file.
• --kind, -k: single_file | zip (inferred from the extension if omitted).
• --notes: Free-text notes for this version.

Secrets#

kiwi distro add-service-secrets — Attach one or more secret names (from the secrets store) to a service.

• --service-id, -sid (required): Service id.
• --secrets, -s (required): Comma-separated secret names to attach.

kiwi distro delete-secret — Delete a secret from the store by key.

• --key, -k (required): Secret key to delete.

kiwi distro get-secret — Show one secret by key. The value is masked unless --reveal is passed.

• --key, -k (required): Secret key.
• --reveal, -r: Show the secret value in plaintext.

kiwi distro list-secrets — List secrets in the store. Values are masked unless --reveal is passed.

• --reveal, -r: Show secret values in plaintext.

kiwi distro remove-service-secrets — Detach one or more secret names from a service.

• --service-id, -sid (required): Service id.
• --secrets, -s (required): Comma-separated secret names to detach.

kiwi distro store-secret — Create or overwrite a secret in the store.

• --key, -k (required): Secret key.
• --type, -t: internal (literal value) | external (value is a resolver reference). Default: internal.
• --value, -val (required): Secret value (internal) or resolver reference such as an ARN (external).

Service groups#

kiwi distro create-service-group — Create a service group — a grant target for client-side authorization.

• --name, -n (required): Group name.
• --desc, -d: Group description.
• --services, -s: Comma-separated member service ids.

kiwi distro delete-service-group — Delete a service group. Rejected for the reserved all-services group.

• --service-group-id, -gid (required): Service group id.

kiwi distro get-client-allowed-service-groups — Show the service-groups a client may call every member of.

• --client-id, -cid (required): Client id.

kiwi distro get-service-group — Show one service group.

• --service-group-id, -gid (required): Service group id.

kiwi distro list-service-groups — List all service groups.

kiwi distro set-client-allowed-service-groups — Set the service-groups this client may call every member of. Empty clears the grant.

• --client-id, -cid (required): Client id.
• --groups, -g: Comma-separated service-group ids. Omit/empty to clear the grant.

kiwi distro set-service-group-members — Replace a service group's member service ids. Rejected for the reserved all-services group.

• --service-group-id, -gid (required): Service group id.
• --services, -s (required): Comma-separated member service ids.

Service-to-service authorization#

kiwi distro get-allowed-callers — Show the caller services allowed to invoke a service (empty = unrestricted).

• --service-id, -sid (required): Service id.

kiwi distro get-method-restrictions — Show all configured method-level restrictions for a service (methods with no entry are unrestricted).

• --service-id, -sid (required): Service id.

kiwi distro remove-method-restriction — Remove a method-level restriction — the method reverts to unrestricted (still subject to the service-level check).

• --service-id, -sid (required): Service id.
• --method, -m (required): Method name.

kiwi distro set-allowed-callers — Set the caller services allowed to invoke a service (service-level authorization). Empty clears the restriction — the service reverts to unrestricted.

• --service-id, -sid (required): Service id.
• --callers, -c: Comma-separated caller service ids. Omit/empty to clear the restriction (unrestricted).

kiwi distro set-method-restriction — Restrict one method to specific caller services — a refinement of an already-permitted service relationship, not an implicit allow-list of every method.

• --service-id, -sid (required): Service id.
• --method, -m (required): Method name.
• --callers, -c (required): Comma-separated caller service ids allowed to invoke this method.

Services#

kiwi distro create-service — Create a new service.

• --name, -n (required): Service name.
• --desc, -d: Service description.
• --secrets, -s: Comma-separated secret names.

kiwi distro delete-service — Delete a service by id.

• --service-id, -sid (required): Service id to delete.

kiwi distro get-service — Show one service by id, including its attached secret names.

• --service-id, -sid (required): Service id.

kiwi distro list-services — List services, optionally filtered by name / description / type.

• --name, -n: Text contained in the service name.
• --desc, -cd: Text contained in the service description.
• --type, -t: Service type to filter on.

SideCar mappings#

kiwi distro delete-sidecar-mappings — Remove the sidecar mapping document for a service.

• --service-id, -sid (required): Service id.

kiwi distro get-sidecar-mappings — Show the sidecar mapping metadata for a service (add --document for the full JSON).

• --service-id, -sid (required): Service id.
• --document, -d: Print the full stored mapping document instead of the metadata.

kiwi distro upload-sidecar-mappings — Upload (or replace) the API-proxy mapping document for a service's sidecar.

• --service-id, -sid (required): Target service id.
• --file, -f (required): Path to the mapping document (JSON).

Sign in#

kiwi distro signin — Sign in to the Kiwi middleware with client credentials (token cached for later commands).

• --client-id, -cid: Client id.
• --client-secret, -cs: Client secret.
• --credentials-file, -cf: JSON file with client_id / client_secret.

Worker profiles#

kiwi distro create-worker-profile — Create a worker profile for a service.

• --profile-name, -pn (required): Worker profile name.
• --profile-desc, -pd: Worker profile description.
• --service-id, -sid (required): Owning service id.

kiwi distro delete-worker-profile — Delete a worker profile.

• --worker-profile-id, -pid (required): Worker profile id.

kiwi distro disable-worker-profile — Disable a worker profile.

• --worker-profile-id, -pid (required): Worker profile id.

kiwi distro enable-worker-profile — Enable a worker profile.

• --worker-profile-id, -pid (required): Worker profile id.

kiwi distro list-worker-profiles — List worker profiles, optionally filtered by service / name. Never shows auth_secret.

• --service-id, -sid: Filter by owning service id.
• --name, -pn: Text contained in the profile name.

Workers#

kiwi distro get-worker — Show a worker's details.

• --worker-id, -wid (required): Worker id.

kiwi distro list-workers — List workers, optionally filtered by name / service / tags / IP range.

• --worker-name, -wn: Text contained in the worker name.
• --service-id, -sid: Filter by service id.
• --tags, -t: Comma-separated tag filters, e.g. os=win10,group=infra.
• --ip-range, -ipr: IPv4 CIDR, e.g. 127.0.0.0/24.