@keystrokehq/skills 0.0.1 → 0.0.2

package/keystroke-cli-workspace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keystroke-cli-workspace
-description: Use the Keystroke CLI to initialize projects, inspect commands, build workflows, deploy workflows or tasks, manage credentials, connect integrations, and debug authoring work. Use when the user needs Keystroke CLI usage or project lifecycle guidance.
+description: Use the Keystroke CLI to initialize projects, inspect commands, build workflows, deploy or manually run deployed workflows, manage credentials, connect integrations, and debug authoring work. Use when the user needs Keystroke CLI usage, workflow run/log guidance, or project lifecycle guidance.
 ---
 
 # Keystroke CLI Workspace
@@ -37,6 +37,7 @@ Teach the CLI as the operational companion to authored code:
 - initialize a project
 - inspect and validate workflows
 - deploy workflows, agents, and tasks
+- manually run deployed workflows from the current deployment
 - connect official integrations
 - inspect and upload credentials
 - sync Keystroke-authored skills into local IDE skill directories
@@ -67,6 +68,7 @@ Important distinctions:
 - `keystroke deploy --target <file>` deploys a focused workflow, agent, or task source file
 - `keystroke logs` is CLI diagnostics
 - `keystroke workflows logs` is workflow run inspection
+- `keystroke workflows run <authoredWorkflowId>` manually starts the currently deployed workflow snapshot
 
 ## Default CLI process
 
@@ -75,7 +77,8 @@ Important distinctions:
 3. Build or validate authored workflows.
 4. Check credentials or connect integrations when required.
 5. Deploy the project or focused target with the right command.
-6. Use logs and inspect commands for debugging.
+6. Run deployed workflows manually when needed.
+7. Use logs and inspect commands for debugging.
 
 ## CLI rules
 
@@ -84,6 +87,7 @@ Important distinctions:
 - Use `keystroke connect <integration>` for official integration connection flows.
 - Use `keystroke credentials ...` for credential inspection and upload flows.
 - Use `keystroke skills sync` to copy `@keystrokehq/skills` into local editor skill directories.
+- Use `keystroke workflows run <authoredWorkflowId>` for deployed-workflow manual invocation; use `try-deploy` only when testing a temporary build artifact.
 
 ## References
 

package/keystroke-cli-workspace/references/command-map.md

@@ -36,7 +36,7 @@ Root help shows these directly. Subcommand help focuses on the local flags for t
 - `projects`: inspect cached project state
 - `connect`: connect official integrations through OAuth
 - `credentials`: list requirements and upload credentials
-- `workflows`: build, validate, inspect, diff, env, logs, paused, try-deploy
+- `workflows`: build, validate, inspect, diff, env, logs, paused, run, try-deploy
 - `test`: test workflows and agent-callable tools
 - `deploy`: deploy workflows, agents, tasks, or focused targets via `--target <file>`
 - `sync`: local sync operations
@@ -46,5 +46,39 @@ Root help shows these directly. Subcommand help focuses on the local flags for t
 ## Command notes
 
 - `keystroke workflows logs` is different from `keystroke logs`
+- `keystroke workflows run <authoredWorkflowId>` executes the current deployed workflow snapshot via the workflow execute API; it does not build or upload local code
+- `keystroke workflows try-deploy <workflow>` builds local code, uploads or references a test bundle, and runs that temporary artifact
 - `keystroke deploy --target <file>` is the focused deploy path
 - many commands support `--json`
+
+## Deployed workflow manual run
+
+Inspect first:
+
+```bash
+keystroke workflows run --help
+```
+
+Common forms:
+
+```bash
+keystroke workflows run wf_onboard_user --input '{"email":"user@example.com"}'
+keystroke workflows run wf_onboard_user '{"email":"user@example.com"}'
+keystroke workflows run wf_onboard_user --input-file payload.json
+keystroke workflows run wf_onboard_user --workflow-globals '{"slackChannel":"#ops"}'
+keystroke workflows run wf_onboard_user --project-id 00000000-0000-4000-8000-000000000001 --input '{}'
+keystroke workflows run wf_onboard_user --input '{}' --wait
+keystroke workflows run wf_onboard_user --input '{}' --follow
+keystroke workflows run wf_onboard_user --input '{}' --json
+```
+
+Project resolution:
+- `--project-id <uuid>` wins when provided
+- otherwise the CLI reads `projectId` from `keystroke.config.ts` discovered from `--path` or CWD
+- auth selects API/org context, but does not imply a default project
+
+Input and globals:
+- workflow input can come from positional payload, `--input`, or `--input-file`; use only one
+- workflow globals can come from `--workflow-globals` or `--workflow-globals-file`; use only one
+- required workflow globals must be provided unless the deployed globals schema supplies defaults
+- credential bindings are intentionally not exposed in the first CLI command surface; the server uses configured credential defaults

package/keystroke-cli-workspace/references/project-lifecycle.md

@@ -66,6 +66,22 @@ keystroke deploy --help
 keystroke deploy
 ```
 
+## Run deployed workflows manually
+
+Use this when the workflow already exists in the project's current deployment and you want an on-demand run without a trigger:
+
+```bash
+keystroke workflows run --help
+keystroke workflows run wf_onboard_user --input '{"email":"user@example.com"}'
+```
+
+Notes:
+- `workflows run` executes the current deployed snapshot through `client.workflows.execute()` / `POST /api/v1/workflows/execute`
+- it does not build or upload local source; use `workflows try-deploy` for temporary local artifact testing
+- pass `--project-id <uuid>` outside a project checkout, otherwise the CLI resolves `projectId` from `keystroke.config.ts`
+- pass `--workflow-globals` or `--workflow-globals-file` when the deployed manifest declares required workflow globals without defaults
+- use `--wait` to poll to a terminal status and `--follow` to poll logs/events while waiting
+
 ## Deploy tasks
 
 ```bash

package/keystroke-workflow-authoring/SKILL.md

@@ -193,6 +193,17 @@ When an agent needs to write custom steps, operations, tools, or workflows, it m
 
 Every workflow can be executed on-demand via the API without requiring a trigger. Triggers are only required for automated entry (webhooks, schedules, provider events).
 
+Prefer the CLI for deployed workflow manual runs when operating from a project checkout:
+
+```bash
+keystroke workflows run <authoredWorkflowId> --input '{"accountId":"123"}'
+keystroke workflows run <authoredWorkflowId> --workflow-globals '{"tenantId":"tenant_123"}'
+keystroke workflows run <authoredWorkflowId> --input '{}' --wait
+keystroke workflows run <authoredWorkflowId> --input '{}' --follow
+```
+
+`workflows run` executes the current deployed snapshot. It is different from `workflows try-deploy`, which builds local code and runs a temporary artifact.
+
 To explicitly start a workflow via API:
 - **Endpoint**: `POST /api/v1/workflows/execute`
 - **Body**:
@@ -202,6 +213,13 @@ To explicitly start a workflow via API:
   - `workflowGlobals`: (Optional) Object matching the workflow's globals schema
   - `credentialBindings`: (Optional) Custom credential bindings for the execution
 
+Manual invocation notes:
+- the API path is generic (`/workflows/execute`); workflows do not get per-workflow invoke routes
+- the CLI resolves `projectId` from `keystroke.config.ts` unless `--project-id` is passed
+- if the workflow manifest declares required `workflowGlobals`, callers must supply them unless the globals schema has defaults
+- schema defaults are applied during validation, so defaulted globals can be omitted by the caller
+- credential bindings are only needed to override server-resolved credential defaults
+
 ## When to choose a workflow
 
 Choose a workflow when the automation needs:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/skills",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "private": false,
   "type": "module",
   "publishConfig": {