epismo 1.27.1 → 1.28.1

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
@@ -1,6 +1,6 @@
1
1
  # Epismo CLI
2
2
 
3
- Native command-line interface for [Epismo](https://epismo.ai). It is written in Go and returns JSON, making it useful in terminals, scripts, and agent workflows.
3
+ Use [Epismo](https://epismo.ai) from your terminal, scripts, and AI agents. Save and resume shared work with cases, and use playbooks for reusable guidance.
4
4
 
5
5
  ## Install
6
6
 
@@ -16,315 +16,49 @@ Windows PowerShell:
16
16
  irm https://epismo.ai/install.ps1 | iex
17
17
  ```
18
18
 
19
- Or install with Go or npm:
19
+ Or install with npm or Go:
20
20
 
21
21
  ```sh
22
- go install github.com/epismoai/cli/cmd/epismo@latest
23
22
  npm install -g epismo
23
+ go install github.com/epismoai/cli/cmd/epismo@latest
24
24
  ```
25
25
 
26
- Prebuilt archives, standalone executables, and `checksums.txt` are available from [GitHub Releases](https://github.com/epismoai/cli/releases).
27
-
28
- ## Updating
29
-
30
- The CLI checks GitHub Releases for a newer version at most once every 24 hours in interactive terminals. When an update is available, run:
31
-
32
- ```sh
33
- epismo update
34
- ```
35
-
36
- The command identifies how the active executable was installed and returns the appropriate installation command; it never modifies the executable itself. Default shell installations receive the short command shown above. A custom installation directory is included only when needed. Go and global Node installations receive a manager-specific command when the package manager can be identified. Yarn's global command is returned only for Yarn Classic because modern Yarn does not support that workflow. Set `EPISMO_UPDATE_CHECK=0` to disable automatic checks.
37
-
38
- The npm package contains a dependency-free JavaScript launcher and all supported native binaries. It uses no lifecycle installation scripts and performs no additional downloads during installation. The launcher selects the binary for the current platform and passes its package-manager context to the native CLI. Shell and PowerShell installers write an installation receipt next to the executable; Go installations are identified from embedded build metadata. If the method cannot be determined safely, `epismo update` links to the update instructions without modifying the executable.
26
+ Binaries and checksums are available from [GitHub Releases](https://github.com/epismoai/cli/releases). Run `epismo update` for update instructions for your installation.
39
27
 
40
28
  ## Quick start
41
29
 
42
- Browse public cases without an account:
43
-
44
- ```sh
45
- epismo case list
46
- epismo case get CASE_ID
47
- ```
48
-
49
- Public playbooks work the same way:
50
-
51
- ```sh
52
- epismo playbook list
53
- epismo playbook get PLAYBOOK_ID
54
- ```
55
-
56
- Log in for search, private data, and writes:
57
-
58
30
  ```sh
59
31
  epismo login
60
- epismo workspace list
61
- epismo workspace use acme # optional: save a default workspace by ID or handle
62
- epismo workspace member invite teammate@example.com
63
- epismo workspace invitation revoke INVITATION_ID
32
+ epismo workspace use acme # optional: select your workspace
64
33
  epismo case start --title "Customer onboarding"
65
- epismo --workspace acme playbook search onboarding
66
- epismo playbook resource list --kind cli
67
- epismo playbook create --definition '{"title":"Onboarding","steps":[]}'
68
- ```
69
-
70
- `epismo workspace checkout <workspace-id>` starts a hosted subscription checkout. If the workspace has a cancellation scheduled for the end of its current billing period, it resumes that subscription instead of creating a second one.
71
-
72
- See the [CLI guide](https://epismo.ai/en/docs/cli) for setup and workflow documentation.
73
-
74
- ## Ownership and resource lifecycle
75
-
76
- Playbooks and cases belong to a personal or workspace account, which is also
77
- responsible for their usage charges. Omit `--owner-id` on create, copy, or case
78
- start to use the active workspace, or your personal account when none is selected.
79
- Assignees and maintainers identify responsibility and do not grant access.
80
- Workspace members need explicit sharing unless they exercise owner/admin rights.
81
- `playbook assign` changes `assignedTo`, the shared responsibility field on
82
- playbooks, cases, and tasks. The playbook UI calls this person the maintainer.
83
- Case ownership transfer requires ownership and the latest lock version; it preserves sharing
84
- and assignment but clears derived review reports.
85
-
86
- ```sh
87
- epismo playbook list --archived
88
- epismo playbook restore PLAYBOOK_ID
89
- epismo playbook assign PLAYBOOK_ID --assigned-to USER_ID
90
- epismo case owner transfer CASE_ID --owner-id ACCOUNT_ID --lock-version 2
91
- epismo case list --archived
92
- epismo case archive CASE_ID --lock-version 3
93
- epismo case restore CASE_ID --lock-version 4
94
- epismo case delete CASE_ID --lock-version 5
95
- ```
96
-
97
- Archive and restore require editing access and preserve work. Permanent case
98
- deletion requires ownership, an already archived case, and its current lock
99
- version. It cannot be undone. Get the current lock version from the appropriate
100
- active or archived listing.
101
-
102
- Before removing a workspace member, preview the responsibility/access handover:
103
-
104
- ```sh
105
- epismo workspace member handover WORKSPACE_ID --departing-user-id OLD_USER_ID --successor-user-id NEW_USER_ID
106
- ```
107
-
108
- Use `--preview=false` to execute and `--transfer-open-approvals` to include open
109
- approval tasks. This explicitly grants the successor editing access; normal
110
- reassignment alone does not. Remove membership separately with
111
- `workspace member delete --workspace-id WORKSPACE_ID OLD_USER_ID`, then run the
112
- handover again with `--preview=false --finalize` to clean up intervening changes.
113
- `--finalize` requires membership to have already been removed; it does not remove
114
- the member.
115
- The operation defaults to preview and supports the normal idempotency key and
116
- local `--dry-run` options. Completed approvals and authorship remain history.
117
-
118
- Initial handover preserves direct grants. Workspace member removal clears the
119
- user's direct grants on items owned by that workspace, including completed and
120
- archived items. Finalization repeats cleanup for late grants. Personal and
121
- other-workspace shares remain unchanged.
122
- Team and workspace management authority follow current membership and the
123
- participation workspace's SSO. Non-member direct shares use normal Epismo
124
- authentication. Resource lists
125
- use explicit access and supported publication, with no ownership exception.
126
-
127
- These operations require an API deployment that supports the bundled OpenAPI
128
- contract. Required workspace SSO also applies to CLI and automation credentials;
129
- sign in again when current SSO evidence is missing or expires.
130
-
131
- ## Cases and handoffs
132
-
133
- Start a case, append timeline records, connect dependent workflows, and explore the DAG:
134
-
135
- ```sh
136
- epismo case start --title "Customer onboarding"
137
- epismo case record append CASE_ID --kind output --content "Completed setup"
138
- epismo case record update RECORD_ID --content "Revised setup notes"
139
- epismo case record delete RECORD_ID
140
- epismo case handoff create FIRST_CASE_ID --to-case-id SECOND_CASE_ID
141
- epismo case handoff remove CASE_ID HANDOFF_ID
142
- epismo case handoff graph get CASE_ID --scope connected
143
- epismo case record list CASE_ID --scope ancestors
144
- epismo case get CASE_ID
145
- epismo case review get CASE_ID
146
- epismo case review list CASE_ID --page-size 20
147
- epismo case review list CASE_ID --cursor NEXT_CURSOR
148
- epismo case review get CASE_ID --report-id REPORT_ID
149
- epismo case review generate CASE_ID
150
- epismo case review act CASE_ID --report-id REPORT_ID --proposal-id PROPOSAL_ID --action create
151
- epismo case review act CASE_ID --report-id REPORT_ID --proposal-id PROPOSAL_ID --action dismiss --feedback "Not needed"
152
- epismo case list --status open
153
- ```
154
-
155
- `case get` includes the latest full `review` and generation `review_job` for work
156
- readers; public-only reads omit them. It never fetches history or invokes AI.
157
- Use `case review list` to browse saved dates, verdicts and summaries, newest first,
158
- with `--page-size` and `--cursor`. Use `case review get --report-id` to read a full
159
- historical report. Superseded reports have `historical: true` and are read-only;
160
- creating or dismissing an unhandled proposal from one returns a conflict. Refresh
161
- the latest report before acting. All history reads use current work access and
162
- the current sharing audience.
163
-
164
- The built-in AI evaluates shared case evidence, explaining where work stands,
165
- evidence gaps, and the most useful next decisions with a verdict (`pass`,
166
- `changes_requested`, or `insufficient`). Evaluations run asynchronously on the
167
- worker: `case review generate` queues an evaluation; poll `case review get`
168
- until the job completes. Recommendations (up to 3) are proposed actions that the
169
- user can confirm unchanged as tasks, cases with directed handoffs, playbook suggestions,
170
- or playbooks with their first version using `case review act`, or dismiss with feedback.
171
- Review the full saved proposal before confirming; title, content, and definition overrides
172
- are not accepted. Actions use the proposal identity for retries, so do not supply
173
- `--idempotency-key`. New cases and playbooks use your active billing home with restricted
174
- creator access; source sharing and external sources are not copied. Evidence changes
175
- show an advisory reevaluation notice and do not block actions. Token-priced credits
176
- charge the case owner when a report is committed.
177
-
178
- ## Case sources
179
-
180
- Link external evidence to a case and read its saved content with `case get`.
181
- Slack threads and Discord messages/threads require a connected provider account
182
- in the selected workspace.
183
- For Google Docs, Sheets, or Slides, connect Google Drive and select the file in
184
- Epismo Web first, then link its URL.
185
-
186
- ```sh
187
- epismo case source link CASE_ID --url SOURCE_URL
188
34
  epismo case get CASE_ID
189
35
  ```
190
36
 
191
- Run `epismo case source --help` for get, refresh, and unlink commands, and use
192
- command-level help for access requirements and credit costs.
193
-
194
- Setup: [Slack](https://epismo.ai/en/docs/integrations/slack) · [Discord](https://epismo.ai/en/docs/integrations/discord) · [Google Drive](https://epismo.ai/en/docs/integrations/google-drive).
195
-
196
- ## Access and sharing
197
-
198
- Resources use a nested `access` object with `visibility` (`restricted` or `public`) and UUID-to-role grants (`viewer` or `editor`):
199
-
200
- ```sh
201
- # Set resource access (replaces the access configuration)
202
- epismo playbook access set PLAYBOOK_ID --access '{"visibility":"public","grants":{"11111111-1111-4111-8111-111111111111":"editor"}}'
203
- epismo case access set CASE_ID --access '{"visibility":"restricted","grants":{"11111111-1111-4111-8111-111111111111":"editor"}}'
204
- epismo playbook owner transfer PLAYBOOK_ID --owner-id WORKSPACE_OR_USER_ID
205
-
206
- # Create an independent copy of a published playbook version
207
- epismo playbook copy PLAYBOOK_ID --source-version-id VERSION_ID --owner-id ACCOUNT_ID
208
- epismo playbook copies list PLAYBOOK_ID --all
209
-
210
- # Connect workspaces with shared teams
211
- epismo -w sender team invite TEAM_ID --emails customer@example.com
212
- epismo -w sender team invitation list TEAM_ID
213
- epismo team invitation get TOKEN
214
- epismo -w recipient team invitation accept TOKEN
215
- epismo -w recipient team disconnect TEAM_ID
216
- ```
217
-
218
- `--access` is accepted on `playbook create`, `case start`, `playbook copy`, and access setters. Viewers can read published playbooks and private cases, tasks, records, and linked sources; editors can update content and drafts. Playbook and case updates must retain at least one explicit user or team editor, including when an owner changes sharing. Creation adds the creator as an editor. Editors can archive resources; assignment alone grants no rights. Member removal is rejected if it would remove the final editor from any owned item, including completed and archived items; add a replacement editor first.
219
-
220
- Case and playbook discovery include public resources by default. Use
221
- `--sharing-scope only_me|shared|anyone` on `case list`, `playbook list`,
222
- `playbook search`, or `playbook resource list` to narrow the readable results.
223
- Only_me means a single known user recipient; Shared means multiple users or a
224
- team/workspace recipient; Anyone means public visibility. These filters never
225
- grant access. Playbook discovery also accepts `--assigned-to` for its maintainer.
226
- The former `case popular` command and `--include-public` flag have been removed.
227
-
228
- Run `epismo --help` for command groups, or append `--help` to any group or command for its options.
229
-
230
- Use `epismo examples` for common workflows, `epismo doctor` to inspect local setup, and `epismo completion zsh` (or `bash`, `fish`, `powershell`) to install shell completion.
231
- The source man page is available at [`docs/epismo.1`](docs/epismo.1).
232
-
233
- ## Output and input
234
-
235
- Successful commands write one JSON document to stdout. Progress events, warnings, and errors are written to stderr as newline-delimited JSON (one compact JSON object per line). This keeps output easy to use from scripts and agents while allowing interactive commands to report progress.
236
-
237
- CLI JSON field names and enum values use `snake_case`. Machine-readable warning and error codes use `SCREAMING_SNAKE_CASE`. Input supplied through `--input` accepts both `snake_case` and `camelCase` fields at every nesting level. Do not provide both spellings of the same field in one object. OAuth protocol fields retain their standard wire names such as `access_token` and `grant_type`.
238
-
239
- Interactive prompts such as the email-code input prompt are plain terminal text. All machine-readable diagnostic records remain one-line JSON objects.
240
-
241
- ```json
242
- {
243
- "error": {
244
- "code": "NOT_FOUND",
245
- "message": "...",
246
- "retryable": false
247
- }
248
- }
249
- ```
250
-
251
- Progress and warnings use a common event envelope:
252
-
253
- ```json
254
- {
255
- "event": {
256
- "level": "info",
257
- "code": "BROWSER_WAITING",
258
- "message": "Waiting for authorization in your browser...",
259
- "details": { "timeout_seconds": 300 }
260
- }
261
- }
262
- ```
37
+ Public cases and playbooks can be browsed before login. Private work and writes require authentication.
263
38
 
264
- Commands that accept a request body support inline JSON, a file, or stdin:
39
+ ## Find what you need
265
40
 
266
41
  ```sh
267
- epismo case record append CASE_ID --input - < record.json
268
- epismo playbook create --input @playbook.json
42
+ epismo --help
43
+ epismo case --help
44
+ epismo examples
269
45
  ```
270
46
 
271
- Explicit flags override fields supplied through `--input`. Mutations create an idempotency key automatically unless you provide `--idempotency-key` or `idempotency_key` in the input.
47
+ Append `--help` to any command for its arguments and options.
272
48
 
273
- ## Everyday terminal use
49
+ - [CLI guide](https://epismo.ai/en/docs/cli): setup and everyday workflows.
50
+ - [Command reference](https://epismo.ai/en/docs/cli/reference): available commands and global options.
51
+ - [Cases guide](https://epismo.ai/en/docs/cli/cases): records, tasks, handoffs, reports, and sharing.
274
52
 
275
- The default output is JSON for scripts and agents. Choose a human-friendly output format when working interactively:
53
+ ## Scripts and agents
276
54
 
277
- ```sh
278
- epismo workspace list --output table
279
- epismo case list --output jsonl
280
- epismo credit checkout --quantity 500 --output value --field checkout_url
281
- epismo playbook search --query onboarding --jq '.playbooks[] | .id'
282
- ```
55
+ Commands return JSON on stdout; errors and progress go to stderr. Output fields use `snake_case`. Use `--output table` for interactive reading, or `--input @file.json` and `--input -` for JSON input from a file or stdin.
283
56
 
284
- Global options may appear before or after the command:
285
-
286
- ```sh
287
- EPISMO_WORKSPACE=acme epismo case list
288
- epismo --workspace acme playbook list
289
- epismo -w acme task list --all
290
- ```
291
-
292
- Workspace references accept an exact ID or unique handle. The effective workspace is chosen in this order: `--workspace`, `EPISMO_WORKSPACE`, a workspace-scoped token, then the saved default workspace. A scoped token cannot grant access outside its scope.
293
-
294
- `--dry-run` previews any command that changes remote or local state without sending a request, opening an authorization or checkout flow, or changing local configuration. This includes creates, updates, publishes, draft saves, assignments, records, handoffs, aliases, membership changes, archive/delete/revoke/close operations, and login/logout or workspace-selection changes. Read-only commands reject `--dry-run` instead of silently ignoring it. In an interactive terminal, especially impactful operations still ask for confirmation during a real run; pass `--yes` to skip that prompt in scripts that allocate a TTY.
295
-
296
- `--input` also works on list/search commands for agent workflows; there it supplies query parameters rather than a request body.
297
-
298
- ## Authentication and configuration
299
-
300
- `epismo login` opens a browser-based OAuth login. With `--email`, it automatically uses your organization SSO when available, otherwise it prompts for an email code.
301
-
302
- `epismo case get`, `epismo case list`, `epismo case record list`, `epismo case handoff graph get`, `epismo playbook list`, and UUID-based `epismo playbook get` work before login for public cases and public playbooks. `epismo case get` accepts a case code (e.g. `PANDA-317`) or UUID. Public case reads expose titles, inputs, tasks, records, readable handoffs, and public author/assignee account references. Private grants, linked sources, review reports and summaries, and private configuration remain omitted. `case get` includes the latest ten records; pass its `records_next_cursor` to `case record list --cursor` with `--scope self` for older public records. Use `case list --playbook-id <id>` to filter discovery. The CLI creates a stable random `anonymousId` in its config for analytics and fair-use rate limiting; it is not an authentication credential. Search, aliases, private data, live case work, and writes still require login.
303
-
304
- For CI or other non-interactive use, create a workspace-scoped token and pass it with `EPISMO_TOKEN`:
305
-
306
- ```sh
307
- epismo token create --workspace-id WORKSPACE_ID
308
- EPISMO_TOKEN=... epismo playbook search
309
- ```
310
-
311
- Configuration is stored in `~/.epismo` (compatible with the original npm CLI). Set `EPISMO_CONFIG_DIR` to use a different directory. For local API development, set `APP_ENV=dev`, or override `EPISMO_API_URL` and `EPISMO_WEB_URL`.
312
-
313
- ## API contract
314
-
315
- [`contracts/openapi.json`](contracts/openapi.json) is a generated snapshot of Epismo's public OpenAPI 3.1 contract. Refresh it after an API deployment:
316
-
317
- ```sh
318
- sh scripts/sync-openapi.sh
319
- ```
320
-
321
- Do not edit the snapshot manually. Its `info.version` represents API compatibility (for example, `1.0.0` for `/v1`), not the CLI release version. Contract tests ensure remote commands and query options remain compatible with the API.
322
-
323
- The OpenAPI snapshot describes the server wire format, which uses `camelCase` for Epismo fields. The CLI translates those fields to and from its public `snake_case` representation at the process boundary.
57
+ For automation, supply a workspace-scoped token through `EPISMO_TOKEN`. Set `EPISMO_WORKSPACE` or pass `--workspace` to select a workspace. Run `epismo doctor` to inspect your setup.
324
58
 
325
59
  ## Develop
326
60
 
327
- The CLI runtime uses only the Go standard library.
61
+ The CLI is written in Go and its runtime uses only the standard library.
328
62
 
329
63
  ```sh
330
64
  go test -race ./...
@@ -332,14 +66,8 @@ go vet ./...
332
66
  go build ./cmd/epismo
333
67
  ```
334
68
 
335
- Releases are built for macOS, Linux, and Windows from semantic-version tags such as `v1.3.1`. The tag is the release version source; the development `package.json` version is intentionally not updated.
69
+ The generated API snapshot lives in [`contracts/openapi.json`](contracts/openapi.json). Refresh it after an API deployment with `sh scripts/sync-openapi.sh`; do not edit it manually. Releases are built from semantic-version tags such as `v1.3.1`.
336
70
 
337
71
  ## License
338
72
 
339
73
  [Apache License 2.0](LICENSE).
340
-
341
- Discovery filters never grant access. Playbook browsing/resources and task lists accept an optional `ownerId` filter for the resource or parent case. Suggestion lists use `playbookOwnerId` for their current parent; suggestions have no independent owner. Use `--input` to pass fields without a dedicated CLI flag. Workspace selection does not implicitly restrict discovery ownership. The Web sidebar narrows team-based discovery only; API and CLI use normal access-based visibility.
342
-
343
- New records and kind changes accept `note` or `output`. Lists accept `note`,
344
- `output`, or server-authored `activity`. Record human and agent assessments as
345
- notes; built-in AI evaluations use reports.
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "epismo",
3
- "version": "1.27.1",
3
+ "version": "1.28.1",
4
4
  "description": "Native CLI for Epismo. Continue work across people and AI agents; JSON for terminals, scripts, and workflows.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",