@solidactions/cli 3.18.0 → 3.20.0

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.
package/README.md CHANGED
@@ -116,6 +116,9 @@ solidactions database list --kind duckdb --json
116
116
  solidactions database show analytics --json
117
117
  solidactions database ingest analytics data.parquet --table events --json
118
118
  solidactions database ingest analytics data.csv --table events --mode replace --json
119
+ solidactions database export analytics --table events --table orders --output ./snapshot
120
+ solidactions database export analytics --no-wait --json
121
+ solidactions database export analytics --resume <export-id>
119
122
  solidactions database drop-table analytics events --yes --json
120
123
  solidactions database optimize analytics --wait --json
121
124
  solidactions database connect analytics --json
@@ -134,7 +137,7 @@ for an analytical database (waits for provisioning unless `--no-wait`).
134
137
  `--from` only applies to the standard kind — `create --kind duckdb --from
135
138
  <file>` is rejected up front, before the database is created, since SQL
136
139
  import is meaningless for an analytical database; load one with `ingest`
137
- after creation. Analytical verbs — `ingest`, `drop-table`, `optimize`,
140
+ after creation. Analytical verbs — `ingest`, `export`, `drop-table`, `optimize`,
138
141
  `connect`, `wake` — only work against a `duckdb` database. `dump`, `pull`,
139
142
  `push`, `import`, and `exec` are for the standard (SQLite) kind only and
140
143
  refuse an analytical name with a one-line hint.
@@ -144,6 +147,17 @@ refuse an analytical name with a one-line hint.
144
147
  this is the normal, expected way to refresh an analytical table from an
145
148
  unattended pipeline, so it is not gated behind confirmation.
146
149
 
150
+ `database export <name>` takes a point-in-time analytical snapshot as one
151
+ ZSTD Parquet file per selected table plus `manifest.json`. With no `--table`
152
+ it exports every user table; repeat `--table` for an exact subset. The default
153
+ waits, verifies every byte length and SHA-256, and writes a new deterministic
154
+ directory. Use `--no-wait` to keep only the accepted export id, `--resume <id>`
155
+ after an interruption, `--output <directory>` to choose the target, and
156
+ `--replace` for non-interactive replacement of a non-reusable ready export.
157
+ `--json` provides machine-readable accepted or verified-terminal output.
158
+ Artifacts expire 24 hours after preparation completes. While the snapshot is prepared, new loads
159
+ pause and the awake database uses organisation credits.
160
+
147
161
  `query` is read-only SQL; use `exec` for writes. `schema`, `query`, `exec`,
148
162
  `pull --writable`, and imports use ephemeral scoped access held only in memory.
149
163
  No durable credential or credential sidecar is written locally.
@@ -436,10 +450,11 @@ Manage agent skills on the crews SOP surface. `push` is an idempotent upsert (cr
436
450
 
437
451
  | Command | Key Flags | Description |
438
452
  |---------|-----------|-------------|
439
- | `skill push <dir>` | `--role <name>`, `--dry-run`, `--json`, `--force` | Push a skill folder, or a whole plugin dir — recursive: pushes every `skills/*/SKILL.md`, converts `commands/*.md` → skills, and ingests each skill's `references/`. `--role` scopes to a role instead of the shared library. Drift-guarded against the local `.solidactions-skill.json` sidecar revision; `--force` skips the guard |
453
+ | `skill push <dir>` | `--role <name>`, `--in-crew <crew>`, `--dry-run`, `--publish`, `--json`, `--force` | Push a skill folder, or a whole plugin dir — recursive: pushes every `skills/*/SKILL.md`, converts `commands/*.md` → skills, and ingests each skill's `references/`. `--role` scopes to a role instead of the shared library; `--in-crew` names the crew that holds the role (with `--role`, to disambiguate a role name that exists in several crews). `--publish` snapshots the skill after pushing so it goes live for agents. Drift-guarded against the local `.solidactions-skill.json` sidecar revision; `--force` skips the guard |
454
+ | `skill publish <name>` | `--role <name>`, `--in-crew <crew>`, `--json` | Publish (snapshot) a skill so its latest pushed revision goes live for agents. With `--role`, publishes that role's role-scoped skill instead of a shared-library skill; `--in-crew` disambiguates the role across crews |
440
455
  | `skill list` | `--json`, `--limit <n>` | List skills in the library |
441
456
  | `skill view <name>` | `--json` | Show one skill |
442
- | `skill pull <name> [dest]` | `--json` | Fetch a skill to a local folder for editing (inverse of push); writes a `.solidactions-skill.json` provenance sidecar used by `push`'s drift guard |
457
+ | `skill pull <name> [dest]` | `--role <role>`, `--in-crew <crew>`, `--json` | Fetch a skill to a local folder for editing (inverse of push); `dest` defaults to `./<name>/`. `--role` pulls a role-scoped skill of that role instead of a shared-library skill; `--in-crew` disambiguates the role across crews. Writes a `.solidactions-skill.json` provenance sidecar used by `push`'s drift guard. `--json` prints the raw read result and writes no files |
443
458
  | `skill delete <name>` | `--json` | Delete a skill (Admin only) |
444
459
  | `skill exec <name> --target sandbox -- <cmd>` (`--target` required) | `--role <name>`, `--in-crew <crew>`, `--environment <env>` (default `production`) | Execute the server-stored skill in its server sandbox (post-push smoke; default env production) |
445
460
  | `skill exec <name> --target host -- <cmd>` (`--target` required) | `--role <name>`, `--in-crew <crew>`, `--crew <nameOrId>`, `--environment <env>` (default `production`), `--env-file <path>` | Execute the server-stored skill on THIS machine via a transparent revision-checked cache — no pull step; crew vars fetched from the platform (default env production; secrets need `env:reveal`) |
@@ -455,11 +470,26 @@ variables; `dev` defaults to `dev`.
455
470
 
456
471
  For `skill dev` / `skill exec`, pass the command as separate words after `--` (e.g. `-- python script.py --flag`); to run a single preformed shell string, wrap it explicitly with `sh -c '...'`.
457
472
 
473
+ **Frontmatter keys.** Frontmatter keys outside the server schema are stored under `metadata` (values that aren't strings are JSON-encoded), and push prints which keys were folded.
474
+
458
475
  ### role
459
476
 
460
477
  | Command | Key Flags | Description |
461
478
  |---------|-----------|-------------|
462
- | `role push <dir>` | `--dry-run`, `--json` | Push a role definition (create or update) |
479
+ | `role push <dir>` | `--in-crew <crew>`, `--replace-links`, `--dry-run`, `--json` | Push a role definition (create or update). `--in-crew` names the crew that holds the role; it is **required to create** a role, and disambiguates the name when it exists in several crews. Without it, an existing role that has that name in exactly one crew is updated in place |
480
+ | `role pull <name> [dir]` | `--in-crew <crew>`, `--no-skills` | Fetch a role and its role-scoped skills to a local folder (inverse of push); `dir` defaults to `./<name>/`. Writes `SKILL.md`, a `.solidactions-role.json` provenance sidecar and `skills/<skill>/` for each role-scoped skill. `--no-skills` pulls the role only. `--in-crew` disambiguates a role name that exists in several crews |
481
+
482
+ **`skill pull` and `role pull` replace the destination atomically.** A pull builds the new folder as `<dest>.tmp-*` beside the destination and then swaps it in, so a failed pull leaves the previous copy untouched. If the process is killed mid-swap, `<dest>.old-*` is the previous copy (rename it back to `<dest>`) and `<dest>.tmp-*` can be deleted. A pull refuses to replace an existing non-empty folder unless it carries the marker file from an earlier pull — `.solidactions-skill.json` for `skill pull`, `.solidactions-role.json` for `role pull` — so a directory that is not a pulled skill or role is never overwritten (nor is the current directory or one of its parents, nor a plain file). The check runs before any network call or write; remove the folder or choose another destination to proceed.
483
+
484
+ **`role pull` pulls the role's published version, with effective values.** A versioned role must have a snapshot (or use `version_mode: live`). Properties the role inherits (`inherits_from`) are merged by the server and pulled as the *effective* value; for such a role, pushing the pulled folder back would store the inherited values on the child, so `role pull` prints a warning. The role's skill preload settings are exported too: `always_load_skills` and `available_skills` are written to the `SKILL.md` frontmatter as skill identifiers (for example `shared/triage`), in the server's order, and `role push` sends them back. Skills in the role's own `skills/` folder are found by the server automatically, so they are not listed in `available_skills`; they travel in `skills/`. Like properties, these lists are the effective merged values.
485
+
486
+ **Creating a role requires `--in-crew`; updating one usually does not.** `role push <dir> --in-crew <crew>` creates the role in that crew if it does not exist and updates it if it does; the crew is never read from the folder's frontmatter. Without `--in-crew`, `role push` looks the role up by name first: if exactly one role has that name it is updated (in its own crew), if none does the push stops and asks for `--in-crew` (a create needs a crew), and if several crews have a role with that name it stops and asks you to choose with `--in-crew`. `--dry-run` follows the same lookup and reports the same result (or the same error) as the real push.
487
+
488
+ **Skill links are preserved on push unless you change them.** `role pull` records the `always_load_skills` and `available_skills` it wrote in `.solidactions-role.json`, along with the role's crew (normalised) and doc id. When you push that folder back to the same role, a link list that still equals the recorded one is kept as it is on the server: it is left out of the update, so every link survives, including skills you cannot see. `role push --dry-run` says which lists it keeps. If you edit a list (a reorder counts, and so does a blank `always_load_skills:`), `role push` exits 1 unless you pass `--replace-links`, because replacing the list deletes links you cannot see. With `--replace-links`, a list you removed from the frontmatter (or left blank) is cleared on the server. Creating a role, or pushing a folder with no `.solidactions-role.json`, sends the lists as written. `--dry-run` applies the same check.
489
+
490
+ **Rate limits.** The server throttles the MCP endpoint that `skill` and `role` use to 60 calls per minute per token. On HTTP 429 the CLI waits the `Retry-After` interval (in seconds or an HTTP date, capped at 60s; 5s if the header is missing or invalid), prints `rate limited by server (429); retrying in <N>s` to stderr, and tries up to 3 times in total before failing with `MCP request failed with HTTP 429`.
491
+
492
+ **Frontmatter keys.** Frontmatter keys outside the server schema are stored under `metadata` (values that aren't strings are JSON-encoded), and push prints which keys were folded.
463
493
 
464
494
  ### doc
465
495
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": 1,
3
3
  "cli_name": "solidactions",
4
- "cli_version": "3.18.0",
4
+ "cli_version": "3.20.0",
5
5
  "global_options": [
6
6
  {
7
7
  "flags": "-V, --version",
@@ -1166,6 +1166,112 @@
1166
1166
  }
1167
1167
  ]
1168
1168
  },
1169
+ {
1170
+ "path": [
1171
+ "database",
1172
+ "export"
1173
+ ],
1174
+ "name": "export",
1175
+ "aliases": [],
1176
+ "description": "Export an analytical database snapshot as Parquet files and a manifest",
1177
+ "hidden": false,
1178
+ "arguments": [
1179
+ {
1180
+ "name": "name",
1181
+ "required": true,
1182
+ "variadic": false,
1183
+ "description": "Database name"
1184
+ }
1185
+ ],
1186
+ "options": [
1187
+ {
1188
+ "flags": "--table <table>",
1189
+ "long": "--table",
1190
+ "short": null,
1191
+ "description": "Export one table (repeatable)",
1192
+ "required": false,
1193
+ "value_required": true,
1194
+ "value_optional": false,
1195
+ "variadic": false,
1196
+ "negated": false,
1197
+ "hidden": false,
1198
+ "default": []
1199
+ },
1200
+ {
1201
+ "flags": "--output <directory>",
1202
+ "long": "--output",
1203
+ "short": null,
1204
+ "description": "Destination directory",
1205
+ "required": false,
1206
+ "value_required": true,
1207
+ "value_optional": false,
1208
+ "variadic": false,
1209
+ "negated": false,
1210
+ "hidden": false
1211
+ },
1212
+ {
1213
+ "flags": "--no-wait",
1214
+ "long": "--no-wait",
1215
+ "short": null,
1216
+ "description": "Print the accepted export id without waiting or downloading",
1217
+ "required": false,
1218
+ "value_required": false,
1219
+ "value_optional": false,
1220
+ "variadic": false,
1221
+ "negated": true,
1222
+ "hidden": false,
1223
+ "default": true
1224
+ },
1225
+ {
1226
+ "flags": "--resume <export-id>",
1227
+ "long": "--resume",
1228
+ "short": null,
1229
+ "description": "Resume an existing authorized export",
1230
+ "required": false,
1231
+ "value_required": true,
1232
+ "value_optional": false,
1233
+ "variadic": false,
1234
+ "negated": false,
1235
+ "hidden": false
1236
+ },
1237
+ {
1238
+ "flags": "--replace",
1239
+ "long": "--replace",
1240
+ "short": null,
1241
+ "description": "Replace a non-reusable ready export without prompting",
1242
+ "required": false,
1243
+ "value_required": false,
1244
+ "value_optional": false,
1245
+ "variadic": false,
1246
+ "negated": false,
1247
+ "hidden": false
1248
+ },
1249
+ {
1250
+ "flags": "--json",
1251
+ "long": "--json",
1252
+ "short": null,
1253
+ "description": "Output as JSON",
1254
+ "required": false,
1255
+ "value_required": false,
1256
+ "value_optional": false,
1257
+ "variadic": false,
1258
+ "negated": false,
1259
+ "hidden": false
1260
+ },
1261
+ {
1262
+ "flags": "-h, --help",
1263
+ "long": "--help",
1264
+ "short": "-h",
1265
+ "description": "display help for command",
1266
+ "required": false,
1267
+ "value_required": false,
1268
+ "value_optional": false,
1269
+ "variadic": false,
1270
+ "negated": false,
1271
+ "hidden": false
1272
+ }
1273
+ ]
1274
+ },
1169
1275
  {
1170
1276
  "path": [
1171
1277
  "database",
@@ -4723,6 +4829,18 @@
4723
4829
  "negated": false,
4724
4830
  "hidden": false
4725
4831
  },
4832
+ {
4833
+ "flags": "--in-crew <crew>",
4834
+ "long": "--in-crew",
4835
+ "short": null,
4836
+ "description": "Crew containing the role (with --role; disambiguates roles in multiple crews)",
4837
+ "required": false,
4838
+ "value_required": true,
4839
+ "value_optional": false,
4840
+ "variadic": false,
4841
+ "negated": false,
4842
+ "hidden": false
4843
+ },
4726
4844
  {
4727
4845
  "flags": "--json",
4728
4846
  "long": "--json",
@@ -4803,6 +4921,30 @@
4803
4921
  }
4804
4922
  ],
4805
4923
  "options": [
4924
+ {
4925
+ "flags": "--role <name>",
4926
+ "long": "--role",
4927
+ "short": null,
4928
+ "description": "Publish a role-scoped skill of this role instead of a shared-library skill",
4929
+ "required": false,
4930
+ "value_required": true,
4931
+ "value_optional": false,
4932
+ "variadic": false,
4933
+ "negated": false,
4934
+ "hidden": false
4935
+ },
4936
+ {
4937
+ "flags": "--in-crew <crew>",
4938
+ "long": "--in-crew",
4939
+ "short": null,
4940
+ "description": "Crew containing the role (with --role; disambiguates roles in multiple crews)",
4941
+ "required": false,
4942
+ "value_required": true,
4943
+ "value_optional": false,
4944
+ "variadic": false,
4945
+ "negated": false,
4946
+ "hidden": false
4947
+ },
4806
4948
  {
4807
4949
  "flags": "--json",
4808
4950
  "long": "--json",
@@ -4853,6 +4995,30 @@
4853
4995
  }
4854
4996
  ],
4855
4997
  "options": [
4998
+ {
4999
+ "flags": "--role <role>",
5000
+ "long": "--role",
5001
+ "short": null,
5002
+ "description": "Pull a role-scoped skill of this role instead of a shared-library skill",
5003
+ "required": false,
5004
+ "value_required": true,
5005
+ "value_optional": false,
5006
+ "variadic": false,
5007
+ "negated": false,
5008
+ "hidden": false
5009
+ },
5010
+ {
5011
+ "flags": "--in-crew <crew>",
5012
+ "long": "--in-crew",
5013
+ "short": null,
5014
+ "description": "Crew containing the role (with --role; disambiguates roles in multiple crews)",
5015
+ "required": false,
5016
+ "value_required": true,
5017
+ "value_optional": false,
5018
+ "variadic": false,
5019
+ "negated": false,
5020
+ "hidden": false
5021
+ },
4856
5022
  {
4857
5023
  "flags": "--json",
4858
5024
  "long": "--json",
@@ -5337,6 +5503,30 @@
5337
5503
  }
5338
5504
  ],
5339
5505
  "options": [
5506
+ {
5507
+ "flags": "--in-crew <crew>",
5508
+ "long": "--in-crew",
5509
+ "short": null,
5510
+ "description": "Crew that contains the role (required to create a role; disambiguates when the name exists in several crews)",
5511
+ "required": false,
5512
+ "value_required": true,
5513
+ "value_optional": false,
5514
+ "variadic": false,
5515
+ "negated": false,
5516
+ "hidden": false
5517
+ },
5518
+ {
5519
+ "flags": "--replace-links",
5520
+ "long": "--replace-links",
5521
+ "short": null,
5522
+ "description": "Replace always_load_skills / available_skills even when they differ from what role pull recorded (the server may hold links you cannot see)",
5523
+ "required": false,
5524
+ "value_required": false,
5525
+ "value_optional": false,
5526
+ "variadic": false,
5527
+ "negated": false,
5528
+ "hidden": false
5529
+ },
5340
5530
  {
5341
5531
  "flags": "--dry-run",
5342
5532
  "long": "--dry-run",
@@ -5375,6 +5565,69 @@
5375
5565
  }
5376
5566
  ]
5377
5567
  },
5568
+ {
5569
+ "path": [
5570
+ "role",
5571
+ "pull"
5572
+ ],
5573
+ "name": "pull",
5574
+ "aliases": [],
5575
+ "description": "Fetch a role and its role-scoped skills to a local folder (inverse of push)\n\nPulls the role's PUBLISHED version: a versioned role must have a snapshot (or use version_mode: live).\nInherited properties are merged by the server (RoleActivator) and are pulled as the effective value.\nFor a role with inherits_from, pushing the pulled folder back would store the inherited values on the child (a warning is printed).\nWrites SKILL.md, .solidactions-role.json and skills/<skill>/ in one atomic replace of the folder.",
5576
+ "hidden": false,
5577
+ "arguments": [
5578
+ {
5579
+ "name": "name",
5580
+ "required": true,
5581
+ "variadic": false,
5582
+ "description": "Role name"
5583
+ },
5584
+ {
5585
+ "name": "dir",
5586
+ "required": false,
5587
+ "variadic": false,
5588
+ "description": "Destination directory (defaults to ./<name>/)"
5589
+ }
5590
+ ],
5591
+ "options": [
5592
+ {
5593
+ "flags": "--in-crew <crew>",
5594
+ "long": "--in-crew",
5595
+ "short": null,
5596
+ "description": "Crew that contains the role (disambiguates when the name exists in several crews)",
5597
+ "required": false,
5598
+ "value_required": true,
5599
+ "value_optional": false,
5600
+ "variadic": false,
5601
+ "negated": false,
5602
+ "hidden": false
5603
+ },
5604
+ {
5605
+ "flags": "--no-skills",
5606
+ "long": "--no-skills",
5607
+ "short": null,
5608
+ "description": "Pull the role only, without its role-scoped skills",
5609
+ "required": false,
5610
+ "value_required": false,
5611
+ "value_optional": false,
5612
+ "variadic": false,
5613
+ "negated": true,
5614
+ "hidden": false,
5615
+ "default": true
5616
+ },
5617
+ {
5618
+ "flags": "-h, --help",
5619
+ "long": "--help",
5620
+ "short": "-h",
5621
+ "description": "display help for command",
5622
+ "required": false,
5623
+ "value_required": false,
5624
+ "value_optional": false,
5625
+ "variadic": false,
5626
+ "negated": false,
5627
+ "hidden": false
5628
+ }
5629
+ ]
5630
+ },
5378
5631
  {
5379
5632
  "path": [
5380
5633
  "role",