@work-shape/catalyst-cli 0.8.0-rc.4 → 0.8.0-rc.41

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@work-shape/catalyst-cli",
3
- "version": "0.8.0-rc.4",
3
+ "version": "0.8.0-rc.41",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -32,6 +32,7 @@
32
32
  },
33
33
  "dependencies": {
34
34
  "js-yaml": "~4.3.2",
35
+ "yaml": "~2.9.1",
35
36
  "zod": "4.4.3"
36
37
  },
37
38
  "devDependencies": {
@@ -39,9 +40,9 @@
39
40
  "@types/node": "^24.13.1",
40
41
  "tsup": "^8.5.1",
41
42
  "typescript": "^6.0.3",
42
- "@work-shape/catalyst-api-client": "0.8.0-rc.4",
43
- "@work-shape/catalyst-api-contract": "0.8.0-rc.4",
44
- "@work-shape/catalyst-asset-schemas": "0.8.0-rc.4"
43
+ "@work-shape/catalyst-api-client": "0.8.0-rc.41",
44
+ "@work-shape/catalyst-api-contract": "0.8.0-rc.41",
45
+ "@work-shape/catalyst-asset-schemas": "0.8.0-rc.41"
45
46
  },
46
47
  "scripts": {
47
48
  "build": "tsup",
@@ -9,12 +9,16 @@ description: Work with a Workshape Catalyst instance through the catalyst comman
9
9
 
10
10
  ## Start here
11
11
 
12
- 1. `catalyst context --json`: the instance, its release, your rights, your Namespaces and the kinds of assets it has.
13
- 2. `catalyst kinds --json`: each kind with its command word, lifecycle and rights.
14
- 3. `catalyst --help`: the commands and options of the CLI that is installed.
12
+ 1. `catalyst context --json`: the instance, its release, your rights, your workspaces and the kinds of assets it has.
13
+ 2. `catalyst kinds --json`: each kind with its command word, lifecycle and rights; `catalyst --help`: the commands and options of the CLI that is installed.
14
+ 3. `catalyst docs`: the index of this release's product docs; `catalyst docs <page>`: one page.
15
15
 
16
16
  Trust these answers over this skill. In a working copy, a command without `--instance` works on the instance its `catalyst.yaml` names as default, and is refused where it names none. Outside a working copy, it works on the one instance saved. When more than one is saved, or the working copy names no default, pass `--instance <name-or-url>` on every command.
17
17
 
18
+ ## When a call fails
19
+
20
+ Run `catalyst doctor` (with the same `--instance` if one was selected). Its four lines check the address, sign-in, versions and effective key rights and are safe to paste into a chat. Never inspect the credentials file to diagnose a call. If versions differ, give the person the exact npm update command it prints. An HTML response usually means the instance address points to a web page or sign-in path: use the HTTPS origin of the instance, without `/api`. Keep install and setup commands on separate lines so they also work in Windows PowerShell 5.1.
21
+
18
22
  ## When the CLI is not logged in
19
23
 
20
24
  A command that answers "Not logged in" or refuses the key needs the person. Stop and ask them to run `catalyst setup <tool> --instance <url>` in their own terminal and confirm the code in their browser. Never ask for a key, never print, paste or pass one, never read the credentials file, and never set `CATALYST_API_KEY` yourself. You cannot issue a key or confirm a code.
@@ -32,6 +36,21 @@ catalyst references --json
32
36
 
33
37
  The kind is the first word: `agent`, `skill`, `guardrail`, `app`, `workflow`, `data-store` or any other kind `catalyst kinds` lists. Add `--workspace <id>` for the assets one workspace owns, and `--json` for the instance's answer as it came.
34
38
 
39
+ ## Where data belongs
40
+
41
+ Decide this before you put data into any asset. A skill folder holds instructions, small fixed reference files and offline calculators: at most 2 MiB a file, 8 MiB and 500 files a skill (`catalyst skill validate` and `put` refuse more). Its scripts run in the instance's sandbox with no network, no secrets and no tools, so never write `curl` or another fetch into a skill script and never put a corpus into a skill folder.
42
+
43
+ - A larger or changing corpus (statutes, manuals, document collections) is a Knowledge Base: filled by upload, by a synced document source such as Dropbox, or by a Workflow that calls the Knowledge Base's `ingest` operation. Cite with dates.
44
+ - Records people or Apps write are a Data Store.
45
+ - An outside system or anything with a credential is a Connection, used by the agent or a Workflow and never by a skill script. An App reaches it only through a named action.
46
+ - An App makes a PDF with the kit's `pdf.download` or `pdf.fromHtml`, never a bundled PDF library. Another file an App makes is generated in the browser with a bundled library and downloaded.
47
+
48
+ Where the 8 MiB or the network stops you, change the design, not the folder. `catalyst docs configure/where-data-belongs` has the page.
49
+
50
+ ## Use a skill of the instance here
51
+
52
+ Only when the person asks to use a skill locally, run `catalyst skill pull <name> .claude/skills/<name>` for Claude Code or `catalyst skill pull <name> .agents/skills/<name>` for Codex. Pulling again refreshes the folder and refuses local edits. Its scripts may assume Catalyst's sandbox, so read them before running them.
53
+
35
54
  ## Change one asset
36
55
 
37
56
  1. Read it with `show` and note its revision.
@@ -41,9 +60,17 @@ The kind is the first word: `agent`, `skill`, `guardrail`, `app`, `workflow`, `d
41
60
 
42
61
  A write names the revision it was made against. When the instance says the asset moved on, read it again and redo the change on the new revision; do not overwrite another person's work. Publish (`catalyst app publish offers --revision 5`) only when the person asks for it.
43
62
 
63
+ An App publish first asks who may use it: only its builder, its owning workspace, or the whole instance where allowed. The person chooses the audience. Pass their stated choice with `--audience` (`self`, `workspace` or `instance`); never choose it for them or widen a live App's audience on your own. A publish run without a terminal needs that explicit flag. A publish goes live at once and asks nothing, so run it only when the person asked for it.
64
+
65
+ ## App and Workflow folders
66
+
67
+ Use `catalyst app pull <app> [dir]` or `catalyst workflow pull <workflow> [dir]` to pull a draft into an empty or new folder; `--published` or `--revision <n>` selects another revision. An App starts with `app.yaml`; a Workflow starts with `workflow.yaml` and its scripts in `steps/`. Both keep `.catalyst-app.json` as their local baseline: leave it in place and never edit or send it.
68
+
69
+ After editing, use `catalyst workflow status <workflow> <dir>` or `catalyst app status <app> <dir>` to inspect the changes. Save them as a draft with `catalyst workflow push [dir]` or `catalyst app push [dir]`. An unchanged Workflow push writes no revision. A stale folder is refused: pull into another folder, carry your changes over and push there. A warning about a possible secret names only its file and line; remove the credential from the source and use a Connection for it. Publish only when asked, through `catalyst workflow publish <workflow> --revision <n>` or the App publish above. Workflows are not part of `catalyst config pull` or `catalyst config push`.
70
+
44
71
  ## A working copy of agents, skills and guardrails
45
72
 
46
- A folder with a `catalyst.yaml` is a working copy. Work in this order:
73
+ In a new folder, first run `catalyst init --instance <url>`. A folder with a `catalyst.yaml` is a working copy. Work in this order:
47
74
 
48
75
  1. `catalyst config pull` before you edit, and again before every push.
49
76
  2. Edit the files.
@@ -86,6 +113,42 @@ These commands print readable YAML; add `--json` for JSON. Paginated lists read
86
113
 
87
114
  `app actions` without a name lists published Apps' actions; with a name it reads the draft if you may write it, otherwise the published revision. `keys list` reads only your own key metadata, never secrets. `instance workspaces` lists Shared Workspaces for agent availability through `instance.workspaces.list`, requiring `config_assets:write` and `agent.write`; it does not list your memberships. Keep `hasMore`, hidden counts and `truncated` in mind when reading hits, dependencies and actions.
88
115
 
116
+ ## Use a Workflow, Data Store or Knowledge Base
117
+
118
+ ```sh
119
+ catalyst workflow start month-end --from input.json # {"input":{"month":"2026-10"}}
120
+ catalyst data-store rows reporting --table bookings --limit 20
121
+ catalyst data-store query reporting --sql "select id from bookings where id = 1"
122
+ catalyst data-store insert reporting --from rows.json # {"table":"bookings","rows":[{"id":1}]}
123
+ catalyst knowledge-base query accounts --sql "select name from accounts"
124
+ ```
125
+
126
+ These need the key's use level. A refusal names the right the key lacks; treat it as final and tell the person, who ticks it in Settings > API keys. Start a Workflow, read rows or insert rows only when asked: `workflow start` runs the published Workflow for real, and `data-store insert` adds rows that stay. `--from <file|->` reads the JSON request body shown above; `knowledge-base query` also takes `{"query": "<named query>", "parameters": {...}}`. `data-store rows` prints one page: pass the `next` it printed as `--after` for the following one.
127
+
128
+ ## Read the instance
129
+
130
+ ```sh
131
+ catalyst usage show
132
+ catalyst audit events --limit 50
133
+ catalyst jobs list --status failed,dead
134
+ catalyst operation runs --since 2026-10-28T00:00:00Z
135
+ catalyst modules list
136
+ catalyst infrastructure show
137
+ ```
138
+
139
+ These read usage, audit events, background jobs, Operation Runs, Modules and infrastructure, and need the key's instance level. The key `catalyst setup` creates does not have it. A refusal names the right the key lacks (`usage.view`, `audit.view` or `system.view`); treat it as final and tell the person, who ticks it for a key of their choice in Settings > API keys. Read them only when asked. Audit events and Operation Runs hold no payload: report them as they are and do not try to recover content from them. `audit events`, `jobs list` and `operation runs` print one page; `--cursor` takes the `nextCursor` it printed.
140
+
141
+ ## Change the account and workspaces
142
+
143
+ ```sh
144
+ catalyst me
145
+ catalyst workspace list
146
+ catalyst workspace members <workspace-id>
147
+ catalyst workspace members add <workspace-id> --email <address>
148
+ ```
149
+
150
+ `me update`, `keys revoke` and the `workspace` commands change the person's own account and their workspaces, and need the key's account and workspaces level (`account.manage`, `collaboration_workspace.manage`). The key `catalyst setup` creates does not have it. Change them only when asked, and show the change first. Never delete a workspace, remove a member or revoke a key without the person's go-ahead for that one change. A refusal names the right the key lacks or says what the person's role in the workspace does not allow; treat it as final and tell the person.
151
+
89
152
  ## Follow a held call
90
153
 
91
154
  A change that exits 3 prints its Operation Run id. Follow it with `catalyst operation show <run-id>` and list your requests with `catalyst requests`. Add `--json` for the full record or list. A held run still exits 3; a failed, denied or expired run exits 1. Withdraw your own request with `catalyst requests --withdraw <id>` only when the person asks; the key needs an asset write or delete scope. Do not send the held change again.
@@ -99,7 +162,7 @@ A change that exits 3 prints its Operation Run id. Follow it with `catalyst oper
99
162
 
100
163
  ## What the key may do
101
164
 
102
- The key acts as the person and never does more than they may at the moment of each call. Its scopes narrow it further, such as `agent.write` everywhere or `agent.write:tax-` in one Namespace. A right an administrator takes away is gone on the next call. The person sees and revokes the key on the instance at `/settings/you/api-keys`.
165
+ The key acts as the person and never does more than they may at the moment of each call. Its scopes narrow it further, such as `agent.write` everywhere, `agent.write:<workspace id>` in one workspace or `agent.write:<workspace id>/<name>` on one of its agents. A right an administrator takes away is gone on the next call. The person sees and revokes the key on the instance at `/settings/you/api-keys`.
103
166
 
104
167
  ## Rules
105
168