npm - @keystrokehq/cli - Versions diffs - 0.1.24 → 0.1.26 - Mend

@keystrokehq/cli 0.1.24 → 0.1.26

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.

Files changed (31) hide show

package/dist/skills-bundle/skills/keystroke-agents/references/tools-mcp-codemode.md DELETED Viewed

@@ -1,85 +0,0 @@
-# Tools, MCP, and codemode
-## Integration actions as tools
-Most agents use imported integration actions:
-```ts
-import { exaSearch, exaAnswer } from "@keystrokehq/exa/actions";
-import { googlesuperFetchEmails, googlesuperSendEmail } from "@keystrokehq/googlesuper/actions";
-tools: [exaSearch, exaAnswer, googlesuperFetchEmails, googlesuperSendEmail],
-```
-See each integration package's `actions` export for available tools.
-## Your own actions as tools
-```ts
-import { triage } from "../actions/triage";
-tools: [triage],
-```
-Same action works in workflows and on agents.
-## Subagents (delegate to another agent)
-Import another agent into `tools` and the parent delegates a scoped task to the child agent:
-```ts
-import { defineAgent } from "@keystrokehq/keystroke/agent";
-import researcher from "./researcher";
-export default defineAgent({
-  slug: "planner",
-  systemPrompt: "Plan work. Delegate research to the researcher subagent.",
-  model: "anthropic/claude-sonnet-4.6",
-  tools: [researcher],
-});
-```
-The tool name is the subagent's `slug`. The tool expects a `message` string parameter.
-## Workflows as tools
-Import a workflow into `tools` when the agent should trigger a fixed multi-step sequence as one durable tool call:
-```ts
-import { defineAgent } from "@keystrokehq/keystroke/agent";
-import refundOrder from "../workflows/refund-order";
-export default defineAgent({
-  slug: "support",
-  systemPrompt: "Help customers. To issue a refund, call the refund-order tool.",
-  model: "anthropic/claude-sonnet-4.6",
-  tools: [refundOrder],
-});
-```
-The tool name is the workflow's `slug`; parameters come from the workflow's `input` schema (must be a Zod object). The workflow runs inline as a tool — it cannot use `ctx.sleep()` or `ctx.hook()`. To run a workflow as its own tracked run instead, call it over HTTP or from a trigger; to reuse it inside another workflow, import it and call `await otherWorkflow.run(input)`.
-## MCP
-Point an agent at an MCP server with `defineMcp` (from `@keystrokehq/keystroke/agent`) and add the definition to `tools` alongside actions. Each tool the server lists becomes available, prefixed with the server `key` (e.g. `mcp__deepwiki__ask_question`).
-```ts
-import { defineAgent, defineMcp } from "@keystrokehq/keystroke/agent";
-const deepwiki = defineMcp({
-  key: "deepwiki",
-  transport: { type: "http", url: "https://mcp.deepwiki.com/mcp" },
-});
-export default defineAgent({
-  slug: "researcher",
-  systemPrompt: "Use the DeepWiki tools to answer questions about repos.",
-  model: "anthropic/claude-sonnet-4.6",
-  tools: [deepwiki],
-});
-```
-For servers that require auth, declare credentials on the definition.
-## Codemode (advanced)
-Default sandbox has bash. For batch tool calls, agents can run js-exec scripts that call `await tools['action-slug'](args)` (the tool name is the action's slug; MCP tools keep their `mcp__<key>__<tool>` prefix). Optional VM runtime via `sandbox: defineSandbox({ mode: "vm" })` (from `@keystrokehq/keystroke/sandbox`).

package/dist/skills-bundle/skills/keystroke-agents/references/workflows-and-testing.md DELETED Viewed

@@ -1,26 +0,0 @@
-# Sessions and workflow handoff
-## Multi-turn CLI
-```bash
-keystroke agent prompt support --message "What is the refund policy?"
-keystroke agent sessions list support
-keystroke agent prompt support --message "Summarize that" --session-id <id>
-```
-## Inspect a session
-```bash
-keystroke agent sessions get support <session-id> --include messages,trace
-```
-Use this when an agent misbehaves or a channel reply looks wrong.
-## Agent called from a workflow
-Actions invoke agents with `.prompt()` inside `defineAction`. Audit the workflow run, not just the agent session:
-```bash
-keystroke workflow runs list signup-pipeline
-keystroke workflow runs get signup-pipeline <run-id> --include steps,trace
-```

package/dist/skills-bundle/skills/keystroke-apps/SKILL.md DELETED Viewed

@@ -1,151 +0,0 @@
----
-name: keystroke-apps
-description: Connectable apps — defineApp, app.action, catalog discovery via keystroke app search, custom app create/sync, and connect. Use when wiring integrations, OAuth, API keys, or a deployed run fails because an app is not connected.
-metadata:
-  keystroke-domain: apps
----
-# Apps
-An **app** is a connectable integration: a slug, an auth kind, and (for custom apps) a field template. **Connected** = secrets for that app have been uploaded via the connect flow.
-Secrets never live in source or `.env`. `keystroke deploy` uploads code only, not connections — connect the apps your project needs with the connect flow.
-Custom actions that call external APIs need a **credential**. The simplest path is a standalone `defineCredential` declared on a `defineAction`. Reach for an **app** (`defineApp` + `app.action()`) when several actions share one connection, or when you've synced a catalog/custom app into `src/apps/`. See [actions skill](.agents/skills/keystroke-actions/SKILL.md).
-## Two sources of apps
-| Source | How you get it | Author in code |
-| ------ | -------------- | -------------- |
-| **Catalog** | ~1000 Composio integrations + first-party (`exa`, `slack`, `googlesuper`) | npm package `@keystrokehq/<slug>` — discover via CLI |
-| **Custom** | Dashboard UI or `keystroke app create`, then `keystroke app sync <slug>` | `src/apps/<name>/app.ts` from sync |
-## Discover catalog integrations
-```bash
-keystroke auth login
-keystroke app search github              # live Composio catalog
-keystroke app show github
-keystroke app actions github --search issue
-keystroke app action GITHUB_CREATE_ISSUE
-keystroke app list                       # apps registered in your org
-```
-Discovery is read-only — there is no `app install` yet. To connect an app, its slug must be in your org registry (`app list`).
-## Create and sync custom apps
-Create in the dashboard or CLI, then pull the template into your project:
-```bash
-# Manual custom app (api_key fields)
-keystroke app create \
-  --name "Internal API" \
-  --description "Our internal service" \
-  --field apiKey:secret
-# Auto-detect from URL (same as dashboard Create custom app)
-keystroke app create --mcp https://mcp.example.com/mcp --preview
-keystroke app create --openapi https://example.com/openapi.yaml --name "Example API"
-keystroke app sync acme/internal-api     # writes src/apps/internal-api/app.ts
-```
-Re-run `sync` after template changes on the platform. Then author actions with `app.action()` in `src/actions/`.
-## Author with defineApp
-Synced apps land as `defineApp` in `src/apps/<name>/app.ts`:
-```ts
-import { defineApp } from "@keystrokehq/keystroke/app";
-import { z } from "zod";
-export const kwatch = defineApp({
-  slug: "keystroke/kwatch",
-  auth: "api_key",
-  credential: { apiKey: z.string() },
-});
-```
-Actions use `app.action()` — the app binding is automatic:
-```ts
-import { kwatch } from "../apps/kwatch/app";
-export const kwatchListAlerts = kwatch.action({
-  slug: "kwatch-list-alerts",
-  input: z.object({}),
-  output: z.object({ ok: z.boolean(), alertCount: z.number() }),
-  async run(_input, credentials) {
-    const { apiKey } = credentials["keystroke/kwatch"];
-    return { ok: true, alertCount: 0 };
-  },
-});
-```
-Auth kinds: `keystroke` (MCP/Composio catalog apps), `api_key` (custom fields), `oauth` (token resolved at runtime). In `run`, read connected fields as `credentials[app.slug]`.
-## Connect an app
-`keystroke connect <slug>` opens the web app connect flow (OAuth or API-key form, depending on the app). This is how secrets get attached to an app — not via `.env`.
-**Official integrations** — the cleanest path:
-```bash
-keystroke connect google
-keystroke connect slack
-keystroke connect exa
-```
-**Custom apps** — sync the template first, then connect:
-```bash
-keystroke app sync acme/internal-api
-keystroke connect acme/internal-api
-```
-The web app **Apps** page offers the same flow.
-Field names in the connect form match the app's synced template. You pick the scope (project / org / user) in the web connect flow — `keystroke connect` has no `--scope` flag. See [cli-and-catalog.md](references/cli-and-catalog.md).
-## Connect what your project needs
-A new project starts with **no connected apps**. After deploy, connect the apps it uses:
-```bash
-keystroke deploy --project <id>
-keystroke connect google
-keystroke connect exa
-keystroke app list
-```
-A runtime error about a missing connection almost always means the app hasn't been connected for this project.
-## Manage & bind credentials
-`keystroke credentials list / get / update --default / rotate-key / delete` manage instances. When several instances share a scope and none is the default, a run can't auto-resolve — set a default, or **bind** an exact instance to one step/tool:
-```bash
-keystroke credentials consumers list --workflow sync                                   # step:<slug>#<n>
-keystroke credentials assignments assign --workflow sync --credential org/work --consumer step:fetch-gmail#0
-keystroke credentials assignments assign --agent support --credential vault-prod --consumer vault-lookup   # tool slug
-```
-An assignment is the explicit selection at the top of the resolution order, so it overrides scope defaults. Full surface: [cli-and-catalog.md](references/cli-and-catalog.md).
-## Audit
-```bash
-keystroke app list                       # org-registered apps
-keystroke credentials list               # connected instances + scope + default
-keystroke credentials assignments list --workflow <slug>   # which instance is pinned where
-```
-Failed integration call → confirm the app is connected for your project, the action uses the right slug, and (if multiple instances) a default or assignment resolves the right one.
-## Next references
-- [cli-and-catalog.md](references/cli-and-catalog.md) — `keystroke app` commands, connect, scopes, credential management & binding
-Related: [cli](.agents/skills/keystroke-cli/SKILL.md), [actions](.agents/skills/keystroke-actions/SKILL.md), [channels](.agents/skills/keystroke-channels/SKILL.md).

package/dist/skills-bundle/skills/keystroke-apps/references/cli-and-catalog.md DELETED Viewed

@@ -1,104 +0,0 @@
-# CLI, catalog, connect
-## Log in once
-```bash
-keystroke auth login
-keystroke auth status
-```
-Token is stored in the OS keychain and reused for all CLI commands. See [cli skill](.agents/skills/keystroke-cli/SKILL.md).
-## keystroke app commands
-All org-scoped; output is JSON.
-| Command | Purpose |
-| ------- | ------- |
-| `app list` | Apps registered/connectable in your org |
-| `app search <query>` | Search live Composio catalog (`--category`, `--limit`, `--cursor`) |
-| `app show <slug>` | Single catalog app details |
-| `app actions [slug]` | List actions for an app, or global search with `--search` (no slug) |
-| `app action <tool-slug>` | Full input/output JSON schema for one action |
-| `app create` | Create custom org app — manual (`--name`, `--slug`, `--description`, `--field`) or auto-detect (`--mcp`, `--openapi`, `--graphql`, `--preview`, `--auth`) |
-| `app sync <slug>` | Write `src/apps/<name>/app.ts` from platform template (`--dir`) |
-`--field` syntax: `key`, `key:secret`, `key:optional`, `key:public`, or combinations like `key:secret:optional` (repeatable). A bare `key` is **secret by default**; `:public` forces a non-secret field. Manual custom apps require at least one `--field`, and at least one of them must be required (not `:optional`).
-With `--mcp`, `--openapi`, or `--graphql`, auth and credential fields are auto-detected from the URL (same as the dashboard Create custom app dialog). Use `--preview` to print the assembled request without creating; override detected values with `--name`, `--slug`, `--description`, `--field`, or `--auth` (`oauth` / `api_key`, MCP only).
-```bash
-keystroke app create --mcp https://mcp.example.com/mcp --preview
-keystroke app create --openapi https://example.com/openapi.yaml --name "Example API"
-```
-## Connect an app
-`keystroke connect <slug>` attaches secrets to an app via the web app connect flow:
-```bash
-keystroke connect google          # official OAuth
-keystroke connect slack
-keystroke connect exa             # official API key
-keystroke connect acme/internal-api   # custom app (sync first)
-keystroke connect <slug> --print-url  # deeplink without opening browser
-```
-- **Official integrations** — always prefer `keystroke connect <slug>`
-- **Custom apps** — `keystroke app sync <slug>` first, then `keystroke connect <slug>`
-- Slug must exist in your org registry (`app list`)
-- The web app **Apps** page offers the same flow
-## Scopes
-A connection is stored at one scope. `keystroke connect` has **no** `--scope` flag — you choose the scope in the web connect flow. To set scope from the CLI, use `keystroke credentials set <key> --scope <scope> [--project-slug <slug>]` (that command defaults to `org`).
-| Scope | When |
-| ----- | ---- |
-| `project` | Tie to one project |
-| `org` | Share with every user and project |
-| `user` | Single user's personal connection |
-At runtime resolution prefers the **project default first, then the org default**. Get the active project id from `keystroke config show`.
-## Manage & bind credentials
-Day-to-day management (output is JSON):
-```bash
-keystroke credentials list                                   # every instance + scope + default flag
-keystroke credentials get <credential-id>
-keystroke credentials update <credential-id> --label "Prod" --default
-keystroke credentials rotate-key <credential-id> --set apiKey=@env:ACME_API_KEY
-keystroke credentials delete <credential-id>
-```
-`--default` marks one instance as the default for its app + scope. When several instances share a scope and none is the default, a run can't auto-resolve — set a default, or **bind** a specific instance to the step/tool that needs it.
-### Bind a specific instance to a step or tool
-An assignment pins an exact credential instance to one consumer. It's the **explicit selection** at the top of the resolution order, so it wins over scope defaults. List the bindable consumers first, then assign:
-```bash
-# Workflow consumers are step correlation ids from recent runs (step:<slug>#<n>)
-keystroke credentials consumers list --workflow sync
-keystroke credentials assignments assign --workflow sync --credential org/work --consumer step:fetch-gmail#0
-# Agent consumers are tool slugs
-keystroke credentials consumers list --agent support
-keystroke credentials assignments assign --agent support --credential vault-prod --consumer vault-lookup
-# Omit --consumer (or pass "*") to bind every consumer on the target
-keystroke credentials assignments assign --workflow sync --credential work
-keystroke credentials assignments list --workflow sync       # inspect bindings
-keystroke credentials assignments unassign <assignment-id>   # remove one
-```
-- Exactly one of `--workflow <slug>` or `--agent <slug>` is required.
-- `--credential` takes an instance slug: `work`, `org/work`, or `<app>/<slug>` (e.g. `linear/work`).
-- Workflow consumer ids only appear after a run has produced `step_completed` events; `consumers list` reads them from recent runs.
-## Where secrets live
-App secrets are **not** read from `.env` and are **never** uploaded by `keystroke deploy` — it ships code only. Attach integration secrets by connecting the app with `keystroke connect <slug>`; they're resolved at runtime for your project.

package/dist/skills-bundle/skills/keystroke-channels/SKILL.md DELETED Viewed

@@ -1,66 +0,0 @@
----
-name: keystroke-channels
-description: Let people use keystroke agents from Slack (external channels) — connect Slack, bind channels with `keystroke channel bind`, pick a listen mode. Use when setting up messaging for agents.
-metadata:
-  keystroke-domain: channels
----
-# External channels
-External channels route **Slack (and similar) messages** to an agent — people chat in-channel instead of using the CLI. Slack is the only channel today.
-## Setup (Slack)
-1. Deploy the agent you want to chat with (`keystroke deploy`)
-2. Connect Slack once for the org: `keystroke connect slack` (or the web app **Apps** page); complete OAuth
-3. Bind a channel to the agent (CLI below, or the agent's **External Channels** panel in the web app)
-4. Message the bound channel per its listen mode
-## Bind from the CLI
-```bash
-keystroke channel platforms list                                  # supported platforms
-keystroke channel accounts --platform slack                       # connected workspaces (team ids)
-keystroke channel directory --platform slack --account <team-id>  # channels you can bind
-keystroke channel bind \
-  --agent support \
-  --platform slack \
-  --account <team-id> \
-  --channel <channel-id> \
-  --mode mention
-keystroke channel list --agent support                            # bindings for an agent
-```
-Listen modes (`--mode`): `mention` (only when @mentioned), `all` (every message), `dm` (direct messages). Update or remove a binding with `keystroke channel update-binding --agent <id> --binding <id> --mode all` / `keystroke channel unbind --agent <id> --binding <id>`.
-`channel bind` also takes an optional `--channel-name <name>` (defaults to the channel id). Every `keystroke channel` subcommand accepts `--project <slug>` to target a non-active project; otherwise they use the active project.
-## What happens at runtime
-Inbound Slack event → lookup channel binding → `runPrompt` for the bound agent → reply in thread.
-The agent acts **on behalf of the channel**, not the sender: it runs with its own tools, actions, and credentials regardless of who messaged. Only bind agents to channels whose members you trust with everything the agent can do.
-## Audit channel-driven sessions
-The CLI session source is still named `gateway`:
-```bash
-keystroke agent sessions list <agent-key> --source gateway
-keystroke agent sessions get <agent-key> <session-id> --include messages,trace
-```
-## Troubleshooting
-| Issue       | Check                                                               |
-| ----------- | ------------------------------------------------------------------- |
-| Bot silent  | `keystroke agent sessions list` for errors; agent on the binding    |
-| "Choose an agent" prompt | The channel has no agent bound — bind one with `keystroke channel bind` |
-| OAuth fails | Slack redirect URLs match your project's web app origin             |
-| Wrong agent | Re-bind with `keystroke channel bind` (or the web app panel)        |
-## Next references
-- [slack-setup.md](references/slack-setup.md) — connect flow, testing against a deployed project
-Related: [agents](.agents/skills/keystroke-agents/SKILL.md), [apps](.agents/skills/keystroke-apps/SKILL.md).

package/dist/skills-bundle/skills/keystroke-channels/references/slack-setup.md DELETED Viewed

@@ -1,41 +0,0 @@
-# Slack channel setup
-## Connect Slack
-Connect the Slack app once for the org with `keystroke connect slack` — the Slack app credentials are entered in the web connect flow, not in your project's `.env`. The connected workspace stays connected; adding more agents is just a bind step.
-Slack OAuth and the inbound routes mount automatically on your **deployed** project, so connecting against the cloud target works out of the box — you don't add Slack to `keystroke.config.ts`.
-## Bind a channel
-```bash
-keystroke channel accounts --platform slack                       # find the team id
-keystroke channel directory --platform slack --account <team-id>  # find the channel id
-keystroke channel bind --agent support --platform slack \
-  --account <team-id> --channel <channel-id> --mode mention
-```
-`--mode` is `mention`, `all`, or `dm`. Thread follow-up is on by default; toggle it with `keystroke channel update-binding --agent <id> --binding <id> --threads` / `--no-threads`.
-The web app offers the same flow from each agent's **External Channels** panel.
-## Testing
-Slack OAuth and the inbound event routes are handled by your **deployed** project — `keystroke dev` (local watch/rebuild) is not in the Slack delivery path. To test Slack end-to-end: `keystroke deploy`, `keystroke connect slack`, `keystroke channel bind …`, then message the bound channel and inspect the session (below).
-> Self-hosting the keystroke platform is a separate concern: that setup seeds Slack app credentials via platform env vars (`SLACK_CLIENT_ID/SECRET/SIGNING_SECRET`) and a public origin (`PUBLIC_PLATFORM_PROXY_URL`). Those are **platform** vars, not part of a scaffolded user project, and `keystroke dev` does not read them.
-## Audit
-```bash
-keystroke agent sessions list <agent-key> --source gateway
-keystroke agent sessions get <agent-key> <session-id> --include messages,trace
-```
-## Common fixes
-| Issue         | Fix                                                |
-| ------------- | -------------------------------------------------- |
-| 401 on events | Check the signing secret in the Slack connection   |
-| No reply      | Session errors via `keystroke agent sessions list` |
-| Wrong agent   | Re-bind with `keystroke channel bind`              |

package/dist/skills-bundle/skills/keystroke-cli/SKILL.md DELETED Viewed

@@ -1,93 +0,0 @@
----
-name: keystroke-cli
-description: Keystroke CLI — log in, manage projects, deploy your src/, and run/inspect what's deployed (workflows, agents, triggers, apps). Use when running keystroke commands for a project.
-metadata:
-  keystroke-domain: cli
----
-# CLI
-The CLI is the primary interface for keystroke projects. You build in `src/`, deploy to your project on the platform, then run and inspect what's deployed. The loop is **edit → deploy → run/inspect → repeat**; deploy often.
-## Log in
-```bash
-keystroke auth login                 # once; token stored in the OS keychain and reused
-keystroke auth login --org <org-slug>  # headless org pick
-keystroke config org                 # list org memberships
-keystroke config use org <org-slug>  # switch active org
-```
-One login covers every command. `auth login` auto-picks your org if you have one and prompts if there are several.
-## Projects
-A **project** is your deploy target on the platform. `keystroke init` scaffolds the local repo; the platform project is where it runs.
-```bash
-keystroke project list
-keystroke project create --name "My app" --description "Optional"
-keystroke deploy --project <id>       # build + upload src/; see deploy skill for --filter
-```
-`--project` selects the deploy target. It's a global flag that works before or after the subcommand (`keystroke deploy --project <id>`).
-New projects are **inactive** until the first deploy. After a deploy, `keystroke deploy` remembers the project (saved in `~/.keystroke`), so later commands target it without `--project`. To switch which project later commands use:
-```bash
-keystroke config use project <id>
-```
-To target a different project for a single command without changing the default:
-```bash
-keystroke workflow runs list greeting --project <id>
-```
-By default the CLI targets the cloud platform. To run commands against a locally running server (`keystroke start` / `keystroke dev`), use the global `--local` flag for one command, or `keystroke config use local` / `keystroke config use cloud` to switch the default target.
-Full deploy, filtered module redeploy, and WIP ignore: [deploy skill](../keystroke-deploy/SKILL.md).
-## Pull an existing project
-`keystroke pull` is the inverse of `deploy`: it downloads a project's **active deploy source** into a local directory, installs dependencies, and syncs bundled skills. Use it to start working on a project that was created or deployed elsewhere (e.g. on a fresh machine).
-```bash
-keystroke pull --project <id>            # into the current directory
-keystroke pull --project <id> --dir ./my-app
-keystroke pull --project <id> --force    # overwrite an existing local tree
-```
-It targets the active project when `--project` is omitted. A directory that already holds an unrelated project is refused unless you pass `--force`; a directory from a prior pull of the **same** project refreshes in place, and a no-op pull (already on the active artifact) exits without changes.
-## Run & inspect
-After deploy, runtime commands operate on your project:
-```bash
-keystroke workflow run greeting --input '{"name":"Ada"}'
-keystroke workflow runs list greeting
-keystroke workflow runs get greeting <run-id> --include steps,trace
-keystroke agent prompt hello --message "Hi"
-keystroke agent sessions get support <session-id> --include messages,trace
-keystroke app list
-keystroke trigger list
-keystroke trigger list --endpoint stripe   # all webhooks on a shared endpoint
-keystroke trigger url stripe               # shared route URL (or a trigger key)
-```
-Always use the CLI to inspect runs and sessions — do not hand-craft HTTP requests.
-## Commands at a glance
-| Command                                            | What it does                                              |
-| -------------------------------------------------- | -------------------------------------------------------- |
-| `auth login`                                       | Authenticate; token reused for all commands              |
-| `project list`, `project create`                   | Manage deploy targets in the active org                  |
-| `deploy`                                           | Build `src/` and ship it; sets the active project        |
-| `pull`                                             | Download a project's active deploy source into a local dir |
-| `workflow`, `agent`, `trigger`, `app`              | Run and inspect resources on your project                |
-| `connect <slug>`                                   | Connect an integration (see apps skill)                  |
-| `config use project <id>`, `config show`           | Set/inspect the active project                           |
-Related: [deploy](../keystroke-deploy/SKILL.md), [apps](../keystroke-apps/SKILL.md), [workflows](../keystroke-workflows/SKILL.md), [agents](../keystroke-agents/SKILL.md), [triggers](../keystroke-triggers/SKILL.md).

package/dist/skills-bundle/skills/keystroke-deploy/SKILL.md DELETED Viewed

@@ -1,93 +0,0 @@
----
-name: keystroke-deploy
-description: Build and deploy keystroke projects — full deploy, filtered module redeploy, @keystroke ignore for WIP modules. Use when shipping to the platform or keeping draft code out of production.
-metadata:
-  keystroke-domain: deploy
----
-# Deploy
-Deploy uploads a `dist/` tarball to the keystroke **platform** and promotes a new project-server runtime (blue/green). Use this skill when shipping your project to the platform.
-## Prerequisites
-```bash
-keystroke auth login
-keystroke project list                    # or: project create --name "My app"
-keystroke deploy --project <slug>         # first deploy must be full (no --filter)
-```
-`--project` selects the deploy target; as a global flag it works before or after `deploy`. After a successful deploy the project becomes the active target (saved in `~/.keystroke`), so later commands (including subsequent deploys) can omit it.
-Deploy always **builds before upload**. Full deploy wipes `dist/` (`clean: true`), rebuilds all modules, regenerates `route-manifest.json`, then packs and uploads.
-## Full deploy
-```bash
-keystroke build                           # optional preview; deploy rebuilds anyway
-keystroke deploy --project <slug>
-keystroke deploy --project <slug> --dir ./my-app
-```
-After success the project becomes the active target for later commands. Verify with `keystroke workflow run <key> --input '{}'`.
-## Filtered deploy (one module)
-Redeploy a single agent/workflow/trigger without rebuilding everything. Requires an **active** artifact from a prior full deploy.
-```bash
-keystroke deploy --project <slug> --filter workflows/morning-check
-keystroke deploy --project <slug> --filter agents/support --filter workflows/signup-pipeline
-```
-`--filter` matches exact build entry keys (`agents/foo`, `workflows/bar`, `triggers/baz`) — the paths under `src/` without extension. Repeat the flag for multiple modules. No globs.
-**How it works:** isolated rebuild of each matched module → download active prod tarball → overlay rebuilt `.mjs` files → merge `route-manifest.json` by module → upload as a normal full deploy.
-**Carried forward from prod:** `config.mjs`, bundled assets, skills metadata, and all untouched modules. Skill/asset drift is not validated in v1.
-Detail: [filtered-deploy.md](references/filtered-deploy.md).
-## WIP modules (`@keystroke ignore`)
-Keep draft agents/workflows/triggers in `src/` but out of the runtime:
-```ts
-// @keystroke ignore          // skip local build, dev, and deploy
-// @keystroke ignore:deploy   // local build + dev only; omitted from deploy
-```
-- `ignore` — broken or not-ready; stays out of `dist/` everywhere.
-- `ignore:deploy` — runs locally; excluded from deploy only.
-Import guard: a shipped module that **imports** an `@keystroke ignore` file fails the build in **every** phase; importing an `@keystroke ignore:deploy` file builds fine locally and fails only at **deploy** time. Triggers attached to an ignored workflow need the same directive.
-Detail: [wip-ignore.md](references/wip-ignore.md).
-## Build vs deploy
-| Command            | Phase   | Output                                      |
-| ------------------ | ------- | ------------------------------------------- |
-| `keystroke build`  | `build` | `dist/` for inspection                      |
-| `keystroke deploy` | `deploy`| `dist/` + upload; honors `ignore:deploy`    |
-Deploy always runs a fresh, clean build before upload.
-Detail: [build-and-full-deploy.md](references/build-and-full-deploy.md).
-## Common mistakes
-- **First deploy with `--filter`** — fails; run full deploy once.
-- **Wrong `--dir`** — builds a different tree than you edited.
-- **Expecting full refresh with `--filter`** — only matched modules rebuild; rest comes from active prod.
-- **Connected apps aren't in `.env`** — deploy never uploads `.env`; connect apps for your project. See [apps skill](../keystroke-apps/SKILL.md).
-## Audit deployed runtime
-```bash
-keystroke project deployments list --project <slug>
-keystroke workflow run morning-check --input '{}'
-keystroke trigger list
-```
-Related: [cli skill](../keystroke-cli/SKILL.md), [apps skill](../keystroke-apps/SKILL.md).