sim 2.1.2-preview.46.1 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +184 -337
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,426 +1,273 @@
1
1
  # Sim CLI
2
2
 
3
- Talk to the [Sim](https://sim.ai) API from your terminal.
3
+ `sim` is the command-line client for [Sim](https://sim.ai), a workspace for
4
+ building, deploying, and managing AI agents and workflows.
4
5
 
5
- ```bash
6
- npm install -g sim
7
- sim login
8
- sim workflows list
9
- ```
10
-
11
- Full documentation: **https://docs.sim.ai/cli**
12
-
13
- ## Profiles
6
+ Use the CLI to work with an existing Sim account or self-hosted deployment from
7
+ your terminal. You can run workflows, inspect logs, query tables, manage files
8
+ and knowledge bases, and configure workspace resources. The CLI does not install
9
+ or run Sim itself; see the
10
+ [self-hosting guide](https://docs.sim.ai/platform/self-hosting/docker) if you need
11
+ to set up a Sim deployment.
14
12
 
15
- Profiles work like the AWS CLI and are selected with `-P`, `--profile`, or
16
- `SIM_PROFILE`. A profile normally owns one identity and one set of defaults; a
17
- workspace profile can instead share a stored identity through `auth_profile`.
13
+ ## Install
18
14
 
19
- Non-secret settings live in `~/.sim/config`:
15
+ The CLI requires Node.js 20 or newer.
20
16
 
21
- ```ini
22
- [default]
23
- endpoint = https://www.sim.ai
24
- workspace = b7f4a1c3-9e02-4d68-8a5b-1c3f6d90e274
25
- output = table
26
-
27
- [profile dev]
28
- endpoint = http://localhost:3000
29
- workspace = a3c81b02-5f4d-4e19-9d7a-2b6c1e084f55
30
-
31
- [profile acme]
32
- auth_profile = default
33
- workspace = 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
34
- ```
35
-
36
- Keys live in `~/.sim/credentials`, written `0600`:
37
-
38
- ```ini
39
- [default]
40
- api_key = sim_…
41
-
42
- [dev]
43
- api_key = sim_…
17
+ ```bash
18
+ npm install --global sim
19
+ sim --version
44
20
  ```
45
21
 
46
- The section-naming asymmetry — `[profile dev]` in config, `[dev]` in credentials
47
- — is the AWS convention, kept so existing habits and tooling carry over.
22
+ You can also run a command without installing the package globally:
48
23
 
49
24
  ```bash
50
- sim configure --set-endpoint http://localhost:3000 --profile dev
51
- sim configure --set-workspace a3c81b02-5f4d-4e19-9d7a-2b6c1e084f55 --profile dev
52
-
53
- sim profiles # list them; * marks the active one
54
- sim whoami # resolved values, where each came from, and whether they work
55
-
56
- # Share the active stored login with a second workspace
57
- sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
25
+ npx sim --help
58
26
  ```
59
27
 
60
- A profile name that is not configured is refused, with the closest configured
61
- name suggested. A typo used to fall through to the built-in defaults, so
62
- `--profile stagng` talked to production and handed it whatever key resolved.
63
- The two exceptions are the commands whose job is to create a profile:
64
- `sim login --profile new` and `sim configure --profile new` still accept a name
65
- that does not exist yet.
28
+ ## Get started
66
29
 
67
- ## Where settings come from
30
+ Sign in to the default profile:
68
31
 
69
- Each setting resolves independently, first match wins:
70
-
71
- | Rank | Source |
72
- | --- | --- |
73
- | 1 | Command-line flag (`--endpoint`, `--workspace`, `--output`) |
74
- | 2 | Environment (`SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT`) |
75
- | 3 | `~/.sim/config` for the selected profile and credentials for its `auth_profile`, when set |
76
- | 4 | Built-in default (`https://www.sim.ai`, `table`) |
77
-
78
- `SIM_TIMEOUT_SECONDS` bounds each request (default `3600`, `0` waits
79
- indefinitely) and `SIM_DEBUG=1` traces requests to stderr. Node ignores
80
- `HTTPS_PROXY` unless `NODE_USE_ENV_PROXY=1` is also set, on Node 22.21+ or
81
- 24.5+; the CLI warns when a proxy is configured but will not be used.
82
-
83
- Formats are listed under [Output formats](#output-formats).
32
+ ```bash
33
+ sim login
34
+ ```
84
35
 
85
- `sim whoami` prints the winning source per setting, which is usually the fastest
86
- way to explain a surprising result. It then reads the configured workspace to
87
- prove the settings actually work; `--no-verify` skips that and stays offline.
36
+ The CLI opens a browser and prints a pairing code. Confirm that the code in the
37
+ browser matches the one in your terminal, approve the login, and choose a
38
+ workspace. The selected workspace becomes the default for this profile.
88
39
 
89
- Its exit status is the answer, so CI can branch on it:
40
+ The login stores a personal API key locally. It does not start a local callback
41
+ server, so the same flow works over SSH and in containers. Use
42
+ `sim login --no-browser` when the browser is on another machine.
90
43
 
91
- | Code | Meaning |
92
- | --- | --- |
93
- | `0` | The key works and reached the configured workspace |
94
- | `1` | The credentials are wrong — no key stored, or the API refused it |
95
- | `2` | The check could not be made — nothing to check against, or the endpoint did not answer |
44
+ Check the active profile and verify that its endpoint, API key, and workspace
45
+ work together:
96
46
 
97
- For CI, skip `sim login` entirely and set `SIM_API_KEY` and `SIM_WORKSPACE` —
98
- nothing needs to touch the filesystem. `SIM_CONFIG_DIR` relocates both files if
99
- you need to keep them somewhere other than `~/.sim`.
47
+ ```bash
48
+ sim whoami
49
+ ```
100
50
 
101
- ## Logging in
51
+ This also reports whether the active key is personal or workspace-scoped. Some
52
+ administrative and deployment operations require a personal key.
102
53
 
103
- `sim login` uses the same browser handoff shape as `gh auth login`: the terminal
104
- prints a pairing code and a URL, you approve in a browser, and the key comes back
105
- over the CLI's own connection. Nothing redeemable crosses the browser leg, and
106
- there is no loopback listener — so it works over SSH and inside containers.
54
+ Then list and run workflows:
107
55
 
56
+ ```bash
57
+ sim workflows list
58
+ sim workflows run <workflowId> --input '{"ticketId":"T-4821"}'
108
59
  ```
109
- $ sim login --profile dev --endpoint http://localhost:3000
110
60
 
111
- Pairing code: K7M2-P9XT
112
- Confirm this code matches what the browser shows before approving.
61
+ A workflow must be deployed before it can run:
113
62
 
114
- http://localhost:3000/cli/auth?request=…&scope=platform
115
- Waiting for approval…
116
-
117
- ✓ Logged in. Key stored in /Users/you/.sim/credentials
118
- Personal key, defaulting to a3c81b02-5f4d-4e19-9d7a-2b6c1e084f55.
119
- Override per command with --workspace.
63
+ ```bash
64
+ sim workflows deploy <workflowId>
120
65
  ```
121
66
 
122
- The approval page is where you pick the workspace — the terminal has no key yet,
123
- so it cannot list them for you. `sim login` issues a personal key, and whichever
124
- workspace you pick becomes only the profile's default `workspace`; it does not
125
- limit the key to that workspace. Use `--workspace` to target another workspace
126
- the key can access.
67
+ Workflow, knowledge-base, and workspace IDs are UUIDs. Table IDs start with
68
+ `tbl_`; file IDs start with `wf_`. Despite the prefix, `wf_` identifies a file,
69
+ not a workflow.
127
70
 
128
- `sim login --workspace <id>` preselects a workspace in the picker, and an
129
- existing profile's workspace preselects itself on re-login.
130
-
131
- ### Personal and workspace keys
71
+ ## Profiles
132
72
 
133
- Some operations accept only a **personal** API key: secrets, knowledge chunks,
134
- knowledge connectors, knowledge tag writes, `chat`, `audit-logs`, and most
135
- workflow deployment writes. A workspace-scoped key gets a `FORBIDDEN` response
136
- on those, under one of two codes:
73
+ A profile is a named CLI configuration. It determines:
137
74
 
138
- - `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — the workspace-scoped operations,
139
- which is most of the list: secrets, knowledge, `chat`, and the deployment
140
- writes.
141
- - `PRINCIPAL_KIND_NOT_PERMITTED` — the organization-scoped ones, which never go
142
- through workspace authorization at all. `audit-logs` is the one in this list.
75
+ - which Sim deployment to use
76
+ - which API key to authenticate with
77
+ - which workspace to target by default
78
+ - how command output is formatted
143
79
 
144
- Match on either when you are branching on the refusal. `sim whoami` reports
145
- which kind you hold on its `Key type` row, and `sim meta status` reports the
146
- same thing as `personal` or `workspace` alongside the rest of the key's state:
80
+ If you do not specify a profile, the CLI uses `default`. Select another profile
81
+ with `--profile`, its short form `-P`, or `SIM_PROFILE`:
147
82
 
148
83
  ```bash
149
- $ sim meta status --output json
150
- {
151
- "v2Enabled": true,
152
- "keyType": "personal",
153
- "expiresAt": null
154
- }
84
+ sim workflows list --profile production
85
+ sim -P production logs list
86
+ SIM_PROFILE=production sim tables list
155
87
  ```
156
88
 
157
- `sim whoami --no-verify` stays offline and so cannot read the key type; it
158
- prints `not checked` instead.
89
+ Unknown profile names fail with the configured profile list and a suggested
90
+ match when available. `login` and `configure` are the exceptions because they
91
+ can create a new profile.
159
92
 
160
- `sim logout` removes the stored key. A shared workspace profile cannot remove
161
- its authentication profile's key; use `sim logout --all --profile <name>` to
162
- remove only the workspace profile. An authentication profile cannot be removed
163
- entirely while workspace profiles reference it. Logging out does not revoke a
164
- key — do that in Settings → API keys.
93
+ There are two common ways to create profiles.
165
94
 
166
- ## Commands
95
+ ### Use one login with several workspaces
167
96
 
168
- The commands below are the common ones. The complete reference — every group,
169
- subcommand, argument, and flag, generated from this package — is at
170
- [docs.sim.ai/cli/commands](https://docs.sim.ai/cli/commands).
171
-
172
- Plural resource names are canonical. Most plural top-level resource groups also
173
- accept their singular form — `sim table list`, `sim file get`, and
174
- `sim workflow get` are equivalent to their plural spellings. The groups with a
175
- singular alias are `audit-logs`, `credentials`, `custom-tools`, `files`, `logs`,
176
- `mcp-servers`, `secrets`, `skills`, `tables`, `workflows`, and `workspaces`;
177
- `blocks`, `tools`, `chat-deployments`, `connector-types`, and
178
- `workflow-mcp-servers` are plural-only. `sim --help` lists each group with the
179
- aliases it actually accepts.
180
-
181
- `knowledge` also accepts the shorter `kb` alias.
97
+ After `sim login`, create another profile that shares the active profile's API
98
+ key but has its own default workspace:
182
99
 
183
100
  ```bash
184
- sim workflows ls [path] [--search <text>] [--limit <n>]
185
- sim workflows list [--folder <path>] [--deployed-only] [--limit <n>]
186
- sim workflows get <id>
187
- sim workflows update <id> [--name <name>] [--description <text>] [--folder <path>]
188
- sim workflows mv <id> <folder>
189
- sim workflows deploy|undeploy|rollback <id>
190
- sim workflows run <id> [--input <json|@file>] [--select-output <path>…] [--async]
191
- sim workflows runs list --workflow <workflowId> [--status <status>]
192
- sim workflows runs get <runId> --workflow <workflowId> [--include-output]
193
- sim workflows runs cancel <runId> --workflow <workflowId>
194
- sim workflows runs resume <runId> --workflow <workflowId> --context <contextId> [--input <json|@file>]
195
-
196
- sim logs list [--level error] [--workflow <id>…] [--trigger <name>…] [--start-date <date>]
197
- sim logs get <runId>
198
-
199
- sim audit-logs list [--organization <organizationId>] [--all-workspaces]
200
- sim audit-logs get <id> [--organization <organizationId>]
201
-
202
101
  sim workspaces list
203
- sim workspaces get
204
- sim workspaces members
205
-
206
- sim tables ls [path] [--search <text>] [--limit <n>]
207
- sim tables list [--folder <path>]
208
- sim tables get <tableId>
209
- sim tables update <tableId> [--name <name>] [--description <text>] [--folder <path>]
210
- sim tables mv <tableId> <folder>
211
- sim tables columns create|update|delete|run <tableId>
212
- sim tables rows list <tableId> [--limit <n>]
213
- sim tables rows create <tableId> --data <json|@file>
214
- sim tables rows create <tableId> --rows <json|@file>
215
- sim tables rows query <tableId> [--filter <json>] [--sort <json>] [--limit <n>]
216
- sim tables rows query <tableId> --filter '{"all":[{"field":"status","op":"eq","value":"active"}]}'
217
- sim tables upsert <tableId> --data <json>
218
- sim tables rows batch-delete <tableId> (--row <id>… | --filter <json>) --yes
219
-
220
- sim files ls [path] [--search <text>] [--limit <n>]
221
- sim files list [--folder <path>]
222
- sim files describe <fileId>
223
- sim files get <fileId> [-o <path>] # stdout by default
224
- sim files create --name <name> [--folder <path>] [--content <value>] [--encoding utf-8|base64]
225
- sim files upload <path> [--name <name>] [--folder <path>]
226
- sim files share get <fileId>
227
- sim files share set <fileId> --is-active <true|false> [--auth-type public|password|email|sso]
228
- sim files mv --file-ids <id>… [--to <path>]
229
- sim files batch-delete --file-ids <id>… --yes
230
- sim files delete <fileId> --yes
231
-
232
- sim knowledge ls [path] [--search <text>] [--limit <n>]
233
- sim knowledge list [--folder <path>]
234
- sim knowledge get <id>
235
- sim knowledge update <id> [--name <name>] [--description <text>] [--folder <path>]
236
- sim knowledge mv <id> <folder>
237
- sim knowledge search --query <text> --kb <id>… [--search-mode vector|hybrid]
238
-
239
- sim knowledge documents list <knowledgeBaseId> [--search <text>]
240
- sim knowledge documents get <knowledgeBaseId> <documentId>
241
- sim knowledge documents upload <knowledgeBaseId> <path> [--tag <value>...]
242
- sim knowledge documents update <knowledgeBaseId> <documentId> [--filename <name>] [--enabled]
243
- sim knowledge documents batch-update <knowledgeBaseId> --operation enable|disable
244
- sim knowledge documents delete <knowledgeBaseId> <documentId> --yes
245
-
246
- sim billing status [--all-workspaces]
247
- sim billing logs [--period 7d] [--source sim-chat] [--limit <n>] [--all-workspaces]
102
+ sim profile add acme --workspace <workspaceId>
103
+ sim --profile acme whoami
248
104
  ```
249
105
 
250
- The `sim-chat` billing source combines Copilot and workspace chat usage.
251
- Organization audit logs require a personal API key; `--organization` defaults
252
- to your only organization and is needed only when you belong to more than one. Commands with
253
- `--all-workspaces` otherwise default to the workspace in the active profile.
106
+ If you omit `--workspace` in an interactive terminal, the CLI asks you to choose
107
+ one. The new profile stores an `auth_profile` reference to the active login; it
108
+ does not copy the API key.
254
109
 
255
- `workflows runs get` is the lightweight status and polling resource.
256
- `--workflow` names the parent resource, while the run ID remains positional.
257
- For a paused run, its status includes the context ID needed by `resume`.
258
- `logs get` is the full diagnostic resource. It keeps the default human output
259
- concise; add `--trace` for the expanded recursive trace with span inputs,
260
- outputs, errors, timing, and cost. JSON and YAML retain the complete structured
261
- response.
110
+ ### Use a separate account or deployment
262
111
 
263
- `sim logs get` keeps the default human output concise. Use JSON or YAML to
264
- inspect its complete `executionData` and recursive `traceSpans` tree:
112
+ Run `login` with a new profile name. Add `--endpoint` when the profile should use
113
+ a self-hosted or local deployment:
265
114
 
266
115
  ```bash
267
- sim logs get <runId> --trace
268
- sim logs get <runId> --output json | jq '.traceSpans'
269
- sim logs list --include-trace-spans --output json
116
+ sim login --profile work
117
+ sim login --profile local --endpoint http://localhost:3000
270
118
  ```
271
119
 
272
- Workflow output selectors use `blockName.field` syntax, such as
273
- `--select-output agent_1.content`; fields that are not produced are omitted.
120
+ Each of these profiles stores its own API key. The endpoint selected during
121
+ login is saved with the profile.
274
122
 
275
- `ls` is a directory view: it combines the resources at its optional path with
276
- that folder's direct child folders. It never includes deeper descendants. Its
277
- `ref` column is the resource ID or canonical folder path to pass to the next
278
- command. Use `list` when you want resources only, or `folders ls` when you want
279
- folders only.
280
-
281
- Each folder-backed resource has the same path commands:
123
+ ### View and change profiles
282
124
 
283
125
  ```bash
284
- sim tables ls Reports
285
- sim tables folders ls --parent Reports
286
- sim tables mkdir Reports/Quarterly
287
- sim tables folders create Reports/Quarterly
288
- sim tables folders mv Reports/Quarterly Archive/Quarterly
289
- sim tables folders delete Archive/Quarterly --yes
290
- sim tables folders delete Archive --recursive --yes
126
+ sim profiles
127
+ sim configure --profile work
128
+ sim configure --profile work --set-workspace <workspaceId>
129
+ sim configure --profile work --set-output json
130
+ sim configure --profile local --set-endpoint http://localhost:3000
131
+ sim whoami --profile work
291
132
  ```
292
133
 
293
- `mkdir` is the concise form of `folders create`. Replace `tables` with `files`,
294
- `workflows`, or `knowledge`. The leading `/` is optional on API inputs; the API
295
- returns the canonical leading-slash form. Omit the `ls` path to list root.
296
-
297
- ### List inputs
134
+ `sim profiles` marks the active profile with `*`. Running `sim configure` with
135
+ no setting flags prints the saved settings for that profile.
298
136
 
299
- Primitive lists take space-separated values. Prefix a path with `@` to read
300
- one value per line, or use `@-` to read the list from stdin.
137
+ Non-secret settings are stored in `~/.sim/config`. API keys are stored separately
138
+ in `~/.sim/credentials`, which is written with `0600` permissions. Set
139
+ `SIM_CONFIG_DIR` to use a different directory.
301
140
 
302
- ```bash
303
- sim files mv --file-ids wf_3Kq9tVbN2xLpR7sWmZ4dY wf_8Jd5cHy1QnT6vXbA0rEuP --to Archive
304
- sim files mv --file-ids @file-ids.txt --to Archive
305
- printf 'wf_3Kq9tVbN2xLpR7sWmZ4dY\nwf_8Jd5cHy1QnT6vXbA0rEuP\n' | sim files mv --file-ids @- --to Archive
306
- ```
141
+ For each setting, the CLI uses the first available value in this order:
307
142
 
308
- File IDs carry a `wf_` prefix, as above. Workflow, knowledge-base, and
309
- workspace IDs are bare UUIDs, and table IDs are `tbl_`-prefixed — the `wf_`
310
- prefix belongs to files, not workflows.
143
+ 1. command-line flag
144
+ 2. environment variable
145
+ 3. selected profile
146
+ 4. built-in default
311
147
 
312
- Arrays of objects remain JSON inputs because they cannot be represented as a
313
- flat list without losing structure.
148
+ `sim whoami` shows both the resolved values and where each one came from.
314
149
 
315
- ### Secret values
150
+ ## Useful commands
316
151
 
317
- `sim secrets set` takes the same `@` convention for its `--value`. Passing a
318
- secret inline exposes it to shell history and to anything reading the process
319
- list, so prefer a file or stdin; the contents are sent verbatim, with no
320
- trimming. A value that genuinely begins with `@` is written `@@`, and only the
321
- leading `@` is dropped. Omit `--value` entirely and the terminal prompts for it
322
- without echoing.
152
+ Run `--help` at any level to see the available subcommands and flags:
323
153
 
324
154
  ```bash
325
- sim secrets set STRIPE_KEY --scope workspace --value @stripe.key
326
- op read op://vault/stripe/key | sim secrets set STRIPE_KEY --scope workspace --value @-
327
- sim secrets set MENTION --scope workspace --value @@channel # the literal @channel
155
+ sim --help
156
+ sim workflows --help
157
+ sim tables rows query --help
328
158
  ```
329
159
 
330
- `--unredacted` marks a workspace secret whose value may appear in run logs and
331
- model-visible content; `--no-unredacted` restores redaction. Omit both and the
332
- secret keeps whatever it had. Both apply only to `--scope workspace`.
160
+ The commands you will use most often are:
333
161
 
334
- ### Filtering table rows
335
-
336
- `--filter` takes the same predicate tree the API uses — `all` (AND) or `any`
337
- (OR) groups of `{field, op, value}` conditions, nestable. It's JSON because the
338
- grammar is a tree; there's no honest flag encoding for it.
339
-
340
- ```bash
341
- sim tables rows query tbl_123 \
342
- --filter '{"all":[{"field":"status","op":"eq","value":"open"},
343
- {"field":"score","op":"gt","value":10}]}' \
344
- --sort '[{"field":"score","direction":"desc"}]' --limit 50
162
+ | Task | Command |
163
+ | --- | --- |
164
+ | Ask Sim about the workspace | `sim chat "Which workflows failed today?"` |
165
+ | List or inspect workflows | `sim workflows list`, `sim workflows get <workflowId>` |
166
+ | Deploy or run a workflow | `sim workflows deploy <workflowId>`, `sim workflows run <workflowId>` |
167
+ | Follow a workflow run | `sim workflows run <workflowId> --follow` |
168
+ | Inspect workflow runs | `sim workflows runs list --workflow <workflowId>` |
169
+ | Find errors | `sim logs list --level error`, `sim logs follow` |
170
+ | Inspect a run trace | `sim logs get <runId> --trace` |
171
+ | Work with tables | `sim tables list`, `sim tables rows query <tableId>` |
172
+ | Import a CSV | `sim tables import ./data.csv` |
173
+ | Upload or download files | `sim files upload ./report.pdf`, `sim files get <fileId>` |
174
+ | Search knowledge bases | `sim knowledge search --query "refund policy" --kb <knowledgeBaseId>` |
175
+ | Upload a knowledge document | `sim knowledge documents upload <knowledgeBaseId> ./handbook.pdf` |
176
+ | Manage integration credentials | `sim credentials --help` |
177
+ | Manage workspace secrets | `sim secrets list`, `sim secrets set <name>` |
178
+
179
+ Commands follow this general shape:
180
+
181
+ ```text
182
+ sim <resource> [sub-resource] <verb> [arguments] [options]
345
183
  ```
346
184
 
347
- `--sort` is JSON for the same reason: it is an ordered list of keys, each with a
348
- `field` and a `direction` of `asc` or `desc`.
185
+ Many plural top-level resource names also accept a singular spelling, so
186
+ `sim workflow get <workflowId>` and `sim workflows get <workflowId>` are
187
+ equivalent. Not every group has a singular alias; `sim --help` shows the exact
188
+ aliases. `knowledge` also has the `kb` alias.
349
189
 
350
- Row columns are discovered at runtime from the returned data, unioned across the
351
- page so a sparse row doesn't hide a column.
190
+ For workflows, tables, files, and knowledge bases, `list` returns resources
191
+ only. `ls [path]` returns the resources and direct child folders at a path:
352
192
 
353
- Deletions require an explicit selector *and* `--yes`; there is no "delete
354
- everything" default.
193
+ ```bash
194
+ sim workflows ls /Support
195
+ sim files ls /Reports
196
+ ```
355
197
 
356
- ### Output formats
198
+ See the [command reference](https://docs.sim.ai/cli/commands) for every command,
199
+ argument, and flag.
357
200
 
358
- Output format can be selected per command with `--output`, saved as a profile
359
- default with `sim configure --set-output <format>`, or set ambiently with
360
- `SIM_OUTPUT` for CI:
201
+ ## JSON input and output
361
202
 
362
- | Format | For |
363
- | --- | --- |
364
- | `table` | reading (default) |
365
- | `json` | piping into `jq` |
366
- | `yaml` | piping into anything that reads YAML |
367
- | `text` | shell loops — tab-separated, no header, no colour |
368
-
369
- `json` and `yaml` emit the API's **raw** values, not the table's formatting — a
370
- duration stays `1500`, not `"1.5s"` — so switching format never changes the data.
371
- `text` uses the rendered cells, since it is meant for shell plumbing rather than
372
- parsing.
203
+ Human-readable tables are the default. Use JSON or YAML when another program
204
+ will consume the result, and `text` for tab-separated shell output:
373
205
 
374
206
  ```bash
375
- sim configure --set-output json # for this profile, from now on
376
- sim configure --set-output text --profile scripts # a profile dedicated to scripting
207
+ sim workflows list --output json
208
+ sim logs list --output json | jq -r '.[].runId'
209
+ SIM_OUTPUT=yaml sim tables get <tableId>
210
+ sim configure --set-output json
211
+ ```
377
212
 
378
- sim --output json logs list --level error | jq -r '.[].runId'
379
- sim logs list --level error --output json | jq -r '.[].runId'
380
- SIM_OUTPUT=yaml sim logs list --level error > logs.yaml
213
+ JSON-valued options accept inline JSON, a file prefixed with `@`, or stdin with
214
+ `@-`:
381
215
 
382
- SIM_OUTPUT=text sim files list |
383
- while IFS=$'\t' read -r id name folder size type uploaded_by uploaded; do
384
- echo "$id $name"
385
- done
216
+ ```bash
217
+ sim workflows run <workflowId> --input '{"customerId":"cus_123"}'
218
+ sim workflows run <workflowId> --input @input.json
219
+ printf '%s' '{"customerId":"cus_123"}' | sim workflows run <workflowId> --input @-
386
220
  ```
387
221
 
388
- An absent value is an em-dash in `table` and an **empty field** in `text`, so
389
- emptiness tests downstream behave.
222
+ List-valued options use the same `@file` and `@-` forms, with one value per
223
+ line. Destructive commands require an explicit selector and `--yes`; they do not
224
+ default to deleting every resource when a selector is missing.
390
225
 
391
- An invalid active `SIM_OUTPUT` or `output =` value fails with the accepted
392
- formats. A valid higher-priority `--output` still overrides a stale lower tier,
393
- so `sim --output table configure --set-output json` can repair a profile.
226
+ For secret values, prefer a prompt, file, or stdin so the value does not appear
227
+ in shell history or the process list:
394
228
 
395
- ## How this stays in sync with the API
229
+ ```bash
230
+ sim secrets set API_KEY --scope workspace
231
+ sim secrets set API_KEY --scope workspace --value @secret.txt
232
+ printf '%s' "$API_KEY" | sim secrets set API_KEY --scope workspace --value @-
233
+ ```
234
+
235
+ ## CI and automation
396
236
 
397
- `src/generated/v2-api.ts` is generated from the Zod route contracts in
398
- `apps/sim/lib/api/contracts/v2/**` — the same contracts the routes validate
399
- against, so a shape that disagrees with them is a shape the server would reject.
400
- It holds every response/request type plus the operation table (method, path,
401
- path params) the client dispatches through.
237
+ In CI, use an API key instead of `sim login`:
402
238
 
403
239
  ```bash
404
- bun run generate:cli-api # regenerate after changing a contract
405
- bun run check:cli-api # CI: fails if the generated file is stale
406
- bun run check:openapi # CI: fails if the docs and contracts disagree
407
- ```
240
+ export SIM_API_KEY="sim_..."
241
+ export SIM_WORKSPACE="<workspaceId>"
408
242
 
409
- The generated file contains only type declarations and one const — no imports —
410
- so the `packages/*` must not import `apps/*` boundary is preserved; the script
411
- does the crossing at build time.
243
+ sim workflows run <workflowId> --input @input.json --output json
244
+ ```
412
245
 
413
- The OpenAPI documents under `apps/docs` are deliberately **not** generated. They
414
- carry hand-written descriptions, examples, and error responses that Zod schemas
415
- don't encode, so regenerating them would trade real documentation for mechanical
416
- accuracy. `check:openapi` reconciles them against the same contracts instead —
417
- field by field, and it parses every documented example with the real Zod schema —
418
- so the prose survives while drift still fails the build.
246
+ Create and revoke API keys in Sim under **Settings → API keys**, and store them
247
+ in your CI provider's secret store. `sim logout` only removes a stored key from
248
+ the current machine; it does not revoke the key.
419
249
 
420
- ## Notes
250
+ The main environment variables are:
421
251
 
422
- - Commands talk to the `/api/v2` surface, which returns `{ data }` and
423
- `{ data, nextCursor }`. List commands auto-page up to `--limit`.
252
+ | Variable | Purpose |
253
+ | --- | --- |
254
+ | `SIM_PROFILE` | Profile to use |
255
+ | `SIM_ENDPOINT` | Sim deployment URL |
256
+ | `SIM_API_KEY` | API key, usually for CI |
257
+ | `SIM_WORKSPACE` | Workspace to target |
258
+ | `SIM_OUTPUT` | `table`, `json`, `yaml`, or `text` |
259
+ | `SIM_CONFIG_DIR` | Directory containing CLI config and credentials |
260
+ | `SIM_TIMEOUT_SECONDS` | Per-request timeout; `0` waits indefinitely |
261
+ | `SIM_DEBUG` | Print request diagnostics to stderr |
262
+
263
+ ## Documentation
264
+
265
+ - [CLI documentation](https://docs.sim.ai/cli)
266
+ - [Command reference](https://docs.sim.ai/cli/commands)
267
+ - [Authentication](https://docs.sim.ai/cli/authentication)
268
+ - [Profiles and configuration](https://docs.sim.ai/cli/configuration)
269
+ - [Scripting](https://docs.sim.ai/cli/scripting)
270
+ - [Troubleshooting](https://docs.sim.ai/cli/troubleshooting)
424
271
 
425
272
  ## License
426
273
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sim",
3
- "version": "2.1.2-preview.46.1",
3
+ "version": "2.1.2",
4
4
  "description": "Sim CLI - talk to the Sim API from your terminal",
5
5
  "type": "module",
6
6
  "bin": {