Use JSON output and explicit authentication/workspace settings for unattended commands. Enable pipeline failure handling in shell scripts so a failed command is not hidden by a successful parser:
See Authentication for CI setup. Examples below assume Bash and jq.
Reading input from files and stdin
JSON flags and primitive-list flags accept @path to read a file or @- to read stdin:
JSON input and the assembled JSON request body have a 10 MiB limit. JSON flags require JSON, including workflow imports; YAML exports must be converted before import. File-aware text flags, such as secret --value, are identified in the command reference; ordinary string flags do not all support file input.
When Sim runs a command inside Chat, @path reads the Chat sandbox rather than workspace Files. Use sim files read for workspace file content. That embedded invocation has no stdin, so use @path or inline input instead of @-.
List flags
Primitive lists use space-separated values. An input file supplies one value per line:
Empty list entries are rejected. Arrays of objects remain JSON. Dependency-manifest flags can ignore blank lines and # comments; this exception does not apply to every list file.
Passing a literal leading @
File-aware flags interpret a leading @ as a file reference. Write @@ to pass a literal leading @; only the first character is removed:
Without escaping, --allowed-emails @example.org tries to open a file named example.org.
Filtering table rows
--filter accepts a predicate tree. Use all for AND, any for OR, and {field, op, value} for a condition. Groups can be nested:
Operators are eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, and isNotNull. Supported operators depend on the column type. Omit value for the empty/null checks.
--sort is an ordered JSON list:
Pagination
Inventory commands such as workflows list and files list, and resource directory ls, fetch all pages by default. Use a limit for a smaller result:
Data/history lists default to 100 items, including table rows and queries, logs, audit/billing events, workflow runs/versions, and knowledge documents/chunks. Connector document lists and other bounded collections also use this default. The command reference states each invocation's limit; these CLI limits differ from API per-page defaults.
--limit 0 fetches every remaining page:
Pages are fetched sequentially, accumulated in memory, and printed as one result. Each paginated API request fetches at most 100 items. For large datasets, use filters or an explicit limit.
Paginated JSON/YAML output has { data: [...], nextCursor }. The cursor follows the last returned row; null ends pagination:
Commands with --cursor can continue from the previous result. Keep the same scope, resource, filters, and sort order:
Run the next command only when the cursor is non-null. --limit applies to each invocation starting at its cursor; --limit 0 --cursor ... fetches all remaining pages. Table-row queries, logs, billing/audit logs, workflow run/version histories, and knowledge document/chunk lists support continuation.
Exit codes
Results go to stdout; diagnostics go to stderr. JSON/YAML modes serialize API errors as {error:{code,message,details?}}. Display formats use Error: plus any supplied code/details. Configuration and argument-parser errors, run-wait outcome messages, and unexpected stack traces can remain text. Do not assume every stderr stream is a single JSON document.
Most successful actions exit 0; API, configuration, or argument failures exit 1. Interactive secret entry cancelled with Ctrl-C exits 130. Other outcomes are command-specific:
Both waits default to 3600 seconds; --wait-timeout 0 waits indefinitely. SIM_TIMEOUT_SECONDS independently bounds one API request. A timeout does not cancel the underlying run or operation.
A synchronous or followed workflow run prints its result before exiting 1 for failure/cancellation. A paused run is not failed and can return 0; use runs wait or inspect status if your script requires completion. Fetching a failed run or listing runs only reports their state.
Capture a failure without losing its output:
For verification failures, inspect the endpoint, credential, and workspace before logging in again:
See Troubleshooting for recovery and reporting unexpected failures.
Polling a long run
Start asynchronously, retain the run ID, then wait:
Time-based pauses continue waiting. Human or unspecified pauses return exit 3 and include the pause context needed by sim workflows runs resume. Inspect the saved result before resuming; use sim logs get "$run_id" --trace --output table for diagnostics.
Starting another run is not an idempotent retry of the first. After a lost response or wait timeout, inspect the existing run rather than starting another execution blindly.
Selecting workflow output
--select-output returns named values in blockOutputs on a synchronous run or its streamed result with --follow. It cannot be combined with --async. Use blockName.field selectors; outputs not produced by the run are omitted:
For a finished run, runs get accepts blockName.path or blockId.path. Names resolve against the workflow's current blocks:
Destructive commands
Deletion requires an explicit target and --yes; omission does not select everything:
Without confirmation, the command explains the consequence and stops. Commands that support a non-writing --dry-run do not require --yes for that preview.
Other commands require confirmation for replacement or cancellation too. Read the command reference for consequences, including chat-setting resets and partial table imports. Cancelling an import does not undo rows already written; replace mode clears the table before loading.
Working with folders
Workflow, table, file, and knowledge-base directories share path commands:
ls lists resources at a path and that folder's direct children. It does not descend further. Pass the displayed ref to the next command. Use list for resources only or folders ls for folders only. A leading / is optional.
Organization access and invitations
Organization commands use --organization; workspace commands use --workspace or the active profile. Get userId from organizations members list or workspaces members list when setting member credit caps, including external collaborators.
access-requests mine shows your requests in the selected scope. Organization access-requests list is the Admin inbox across organization workspaces. Discover the target before submitting:
An Admin previews a request before applying it. Inspect canApply, changes, and impact: a permission approval changes the governing group for all affected members. Apply the reviewed fingerprint; a conflict requires a new preview:
Applying a credit-cap request also requires --new-limit-credits greater than the current cap. To decline, use --action decline --reason 'Explanation'.
An Admin can set a cap directly. Zero prevents further credit-consuming usage; null removes only the per-person cap, leaving organization limits in effect:
Workspace invitations accept up to 50 emails. Recipients are processed independently. Any failure makes the CLI print the full result and exit 1; successful invitations and grants remain committed. Inspect failed and current invitations before retrying, especially when delivery was uncertain:
A nightly job, end to end
This script starts one run, waits for its outcome, and preserves the run ID for recovery. The wait is inside an if so set -e does not exit before outcome handling: