Scripting

Use these patterns to pass inputs, page through results, and handle command outcomes.

Reading input from files and stdin

Any flag that takes JSON or a list also accepts @path to read a file, or @- to read stdin.

sim workflows import --workflow @wf.json
sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --filter @filter.json
cat wf.json | sim workflows import --workflow @-

List flags

Primitive lists take space-separated values. With @, the file supplies one value per line:

sim files mv --file-ids wf_3Qm8ZtLpR2yVnKd7BsXwC wf_5Hn1JvTqW9xUcMb4RzPgL --to Archive
sim files mv --file-ids @file-ids.txt --to Archive
printf 'wf_3Qm8ZtLpR2yVnKd7BsXwC\nwf_5Hn1JvTqW9xUcMb4RzPgL\n' | sim files mv --file-ids @- --to Archive

Arrays of objects stay JSON.

Passing a literal leading @

Because @ introduces a file reference, a value that genuinely starts with one is written @@. Only the leading @ is dropped, and every @-aware flag accepts the escape:

sim files share set wf_3Qm8ZtLpR2yVnKd7BsXwC --is-active true --auth-type email --allowed-emails @@example.org
sim secrets set API_HOST --scope workspace --value @@internal

Without it, --allowed-emails @example.org can only be read as a request to open a file named example.org.

Filtering table rows

--filter takes the same predicate tree the API uses: all (AND) or any (OR) groups of {field, op, value} conditions, nestable.

sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 \
  --filter '{"all":[{"field":"status","op":"eq","value":"open"},
                    {"field":"score","op":"gt","value":10}]}' \
  --limit 50

Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull.

--sort is also JSON, an ordered list of keys:

sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --sort '[{"field":"createdAt","direction":"desc"}]'

Pagination

Resource lists and directory ls follow every page by default. Pass --limit N to cap the returned items:

sim workflows list --output json
sim files ls /Reports --limit 50

Table rows (including queries), logs, audit/billing events, workflow runs and versions, and knowledge documents/chunks retain a default limit of 100. Connector document lists also use this cap. Use --limit 0 to fetch every page of a large dataset:

sim logs list --limit 0 --output json > all-logs.json

Pages are fetched sequentially, accumulated in memory, and printed as one result. A large table can consume substantial memory; use filters or an explicit limit when you only need a subset. Each API request fetches at most 100 items.

Paginated JSON and YAML results have the shape { data: [...], nextCursor }. nextCursor is the cursor after the last returned row, or null when all pages have been fetched. Scripts that read list rows should use .data[]:

sim logs list --output json | jq -r '.data[].runId'

The capped dataset commands accept --cursor to resume from the previous result's nextCursor. Keep the same resource, filters, and sort order, and stop when the cursor is null:

sim tables rows list tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --limit 100 --output json
sim tables rows list tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --limit 100 --cursor "$nextCursor" --output json

--limit applies to each invocation starting at its cursor. --limit 0 with --cursor fetches every remaining page. Table-row queries, logs (including billing and audit logs), workflow run/version histories, and knowledge document/chunk lists all support this continuation.

Destructive commands

Deletions require an explicit selector and --yes. There is no "delete everything" default:

sim tables rows batch-delete tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --row row_2f81c0a94db54e6f8a13c7e0526bd94a row_6b3e59d0af1c42d7b80e94f3a271c568 --yes
sim files delete wf_8Kd2NpVrY6zTfQa3XwBmS --yes

Without --yes the command explains what it would have destroyed and stops.

Exit codes

Errors print one line to stderr, prefixed Error:, plus the API's error code and validation details when it supplies them. Failures are safe to branch on:

if ! sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json > result.json; then
  echo "run failed" >&2
  exit 1
fi

An unexpected error prints a stack trace — that is a bug in the CLI, so please open an issue.

sim whoami splits its failure in two because the fixes differ: 1 means the credentials are wrong and a fresh sim login is the answer, while 2 means the CLI never got a verdict — no workspace to check against, or an endpoint that did not answer — and logging in again would not help.

sim whoami > /dev/null
case $? in
  0) ;;                                  # ready
  1) echo "run: sim login" >&2; exit 1 ;;
  2) echo "endpoint unreachable, retrying later" >&2; exit 75 ;;
esac

Selecting workflow output

--select-output shapes a streamed result, so it requires --follow. It takes blockName.field selectors; fields that a run did not produce are simply omitted:

sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --follow --select-output agent_1.content --output json

Without --follow the CLI refuses the pair rather than spending a request on a response that carries no outputs, and --async cannot be combined with it either — there is no stream to shape. To narrow a run that has already finished, read it back with workflows runs get, which matches block ids rather than the block names workflows run takes:

sim workflows runs get "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 \
  --select-output 1d4c8f02-7b63-4a19-8e52-63f0a7c5d9b1.content --output json

Polling a long run

Start the run asynchronously, then use the CLI’s wait command:

run_id=$(sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --async --output json | jq -r '.runId')
sim workflows runs wait "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --wait-timeout 3600 --output json

The command polls until the run completes, fails, is cancelled, or pauses for human input. Time-based pauses continue waiting. Its exit code identifies the outcome; --wait-timeout 0 waits indefinitely.

Use sim logs get "$run_id" --trace for full diagnostics. A run paused for human input includes the context ID needed by sim workflows runs resume.

Working with folders

Every folder-backed resource — workflows, tables, files, knowledge — shares the same path commands:

sim tables ls Reports
sim tables mkdir Reports/Quarterly
sim tables folders mv Reports/Quarterly Archive/Quarterly
sim tables folders delete Archive --recursive --yes

ls lists the resources at a path plus that folder's direct children, never deeper. Its ref column is the value to pass to the next command. Use list for resources only, or folders ls for folders only. A leading / is optional.

A nightly job, end to end

#!/usr/bin/env bash
set -euo pipefail

export SIM_API_KEY="${SIM_API_KEY:?missing}"
export SIM_WORKSPACE="${SIM_WORKSPACE:?missing}"
export SIM_OUTPUT=json

run_id=$(sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"source":"nightly"}' | jq -r '.runId')

if [ "$(sim workflows runs get "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 | jq -r '.status')" != "completed" ]; then
  sim logs get "$run_id" >&2
  exit 1
fi