@keystrokehq/cli 0.1.50 → 0.1.51

package/README.md

@@ -17,6 +17,41 @@ Keep the CLI small and boring.
 
 Right now the CLI exposes `init`, `build`, `dev`, `start`, `lint`, `typecheck`, `test`, `deploy`, `health`, `auth`, `--help`, and `--version`.
 
+## Command grammar
+
+Stripe-style: plural REST collection, then a verb, then the primary slug. New commands **must** follow this shape.
+
+```text
+keystroke <collection> <verb> [<slug>] [<sub-id>] [--flags]
+keystroke <collection> <sub-collection> <verb> [<slug>] [<sub-id>] [--flags]
+keystroke <verb>                                    # lifecycle only (init, build, dev, deploy, …)
+```
+
+Rules:
+
+- **Collections are plural** and match the HTTP API / SDK / `src/` dirs — `workflows`, `agents`, `triggers`, `projects`, `apps`, `channels`, `credentials`. Never singular.
+- **The primary resource is positional**, not a flag. The collection already names the type, so `workflows run greeting` — never `workflows run --workflow greeting`.
+- **Nested resources are sub-collections before the verb** — `workflows runs list <slug>`, `apps actions get <app> <tool>`. Not flat (`workflows-runs-list`) and not verb-first (`workflows list runs`).
+- **A second positional is the child id** — `workflows runs cancel <workflow> <run-id>`, `agents sessions cancel <agent> <session-id>`.
+- **Flags are for two things only:**
+  - **Payload / options** — `--input`, `--message`, `--include`, `--limit`.
+  - **Scope or a *different* resource type** — global `--project` / `--local`; cross-references like `triggers disable <trigger> --workflow <slug>` where the positional is the trigger and the flag narrows to one attachment. Do not add type-named flags (`--workflow`, `--agent`) to that type's own commands.
+- **Verbs are consistent across collections** — `list`, `get`, `create`, `update`, `delete`, `run`/`execute`/`prompt`. Prefer `get` over `show`, `create` over `set`.
+
+Example command tree:
+
+```text
+keystroke workflows run <slug> --input '{...}'
+keystroke workflows runs list|get|cancel <slug> [<run-id>]
+keystroke agents prompt <slug> --message "…"
+keystroke agents sessions list|get|cancel <slug> [<session-id>]
+keystroke triggers disable|enable <slug> [--workflow <s> | --agent <s>]
+keystroke triggers runs list|get <slug> [--workflow <s> | --agent <s>]
+keystroke apps actions list|get <app> [<tool>]
+keystroke apps execute <app> <tool> --input '{...}'
+keystroke credentials create|get|rotate|delete <key>
+```
+
 ### `auth`
 
 Authenticate with Keystroke via Better Auth device flow. Config lives in `~/.keystroke`; bearer tokens live in the OS keychain.
@@ -68,9 +103,9 @@ keystroke --project <slug> project settings update --description "Notes" --defau
 List triggers and resolve webhook URLs after deploy (requires `keystroke auth login`):
 
 ```bash
-keystroke trigger list
-keystroke trigger get incoming-message
-keystroke trigger url incoming-message
+keystroke triggers list
+keystroke triggers get incoming-message
+keystroke triggers url incoming-message
 ```
 
 `url` prints a single line suitable for piping into curl or pasting into external webhook config.