> ## Documentation Index
> Fetch the complete documentation index at: https://app.keystroke.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI for agents

> How coding agents use the Keystroke CLI.

Keystroke is built for coding agents. The `keystroke` CLI works headlessly out of the box: every command runs non-interactively, invoke and inspect commands print JSON, and the docs are a command away so your agent can learn how Keystroke works as it builds.

This page covers agent-specific behavior. For installation and the full command list, see the [CLI reference](/cli).

## Baseline context and docs

`keystroke init` scaffolds an `AGENTS.md` guide (symlinked to `CLAUDE.md`) with concise baseline context — the CLI, project layout, discovery, and working habits — that most coding agents read automatically. The CLI keeps `AGENTS.md` in sync with your installed version whenever you run a command in the project. Use [`keystroke docs search`](/cli#docs) and [`keystroke docs query`](/cli#docs) for deeper reference.

For anything deeper, your agent reads the docs directly from the CLI — no auth, no project required:

```bash theme={null}
keystroke docs search "webhook trigger"      # find pages by topic
keystroke docs query "cat /quickstart.mdx"   # read a page by path
```

<Card title="Docs for agents" href="/build-with-ai/docs-for-agents">
  How your agent searches and reads the Keystroke docs while it builds.
</Card>

## A deploy-first build loop

Most agent work follows one loop: edit `src/`, deploy to your platform project, then run and inspect what's deployed with the CLI. Deploy often — run a full deploy, or `--filter` to redeploy a single module fast.

**Do not run lint, typecheck, or build as separate steps before deploy.** `keystroke deploy` gates on lint and typecheck automatically — attempt deploy, read the failure, fix, and redeploy.

```bash theme={null}
keystroke deploy --project <id>                 # gates lint + typecheck, then builds and ships dist/
keystroke workflows run greeting --input '{"name":"Ada"}'
keystroke agents prompt support --message "Hi"
keystroke apps execute github github_get_the_authenticated_user  # run a connected catalog action
```

Use `keystroke test` when you want a fast local loop on unit or integration tests — it is not a deploy prerequisite.

After a deploy, runtime commands target that project automatically — your agent has no config to manage. Keep work-in-progress out of deploys with `@keystroke ignore` (see [deploy individual files](/learn/projects/deploy-individual-files)).

`app execute` resolves credentials like the runtime does — project default → org default. In a linked project the project scope resolves automatically; otherwise pass `--project <slug>`. Pin a specific instance (and the only way to use a user credential) with `--credential <slug>`; see [Actions](/cli#actions).

If the project already exists but its code isn't on this machine, `keystroke pull --project <slug>` downloads the active deploy source and installs dependencies — a common way for an agent to bootstrap a working tree before the loop above.

You can also run a local server with `keystroke dev` for offline, no-auth iteration; see [targets: local vs cloud](/cli#targets-local-vs-cloud) for the full resolution order.

## Headless mode

Every command runs without prompts, so agents and CI never block on input.

* `keystroke init my-app --yes` skips all prompts. The CLI also goes headless automatically in a non-TTY environment (piped output, CI runner).
* Destructive commands require explicit confirmation via `-y, --yes` instead of an interactive prompt:

```bash theme={null}
keystroke init my-app --yes
keystroke projects delete --project my-app --yes
keystroke api-key revoke <id> --yes
```

If a required value is missing in headless mode, the command exits with an error describing what's needed rather than waiting for input.

## Machine-readable output

Invoke and inspect commands (`workflow`, `agent`, `trigger`, `history`, `credentials`, `health`, and friends) print JSON to **stdout** so your agent can parse results directly. No flag is needed; JSON is the default for these commands.

```bash theme={null}
keystroke workflows run greeting --input '{"name":"Ada"}' | jq '.runId'
```

Errors are written to **stderr**, and the process exits non-zero on failure:

| Outcome | Exit code | Stream                  |
| ------- | --------- | ----------------------- |
| Success | `0`       | JSON on stdout          |
| Failure | `1`       | Error message on stderr |

Lifecycle commands (`init`, `dev`, `start`, `build`, `deploy`) print human-readable status instead; they drive your project rather than return data.

## Injecting secrets from the environment

Agents should never hardcode secrets. When setting a credential, read the value from an environment variable with `@env:`:

```bash theme={null}
keystroke credentials create exa --scope org --set apiKey=@env:EXA_API_KEY
```

`--set key=@env:VAR` reads `VAR` from the shell, falling back to the project's `.env` when it isn't set in the environment. Use `--set key=value` only for non-sensitive literals.

## Headless OAuth

Connecting a provider opens a browser by default. In a headless environment, print the authorize URL instead so it can be handed to a human to complete:

```bash theme={null}
keystroke connect google --print-url
```

## Closing the loop

After invoking a workflow or agent, your agent can inspect exactly what happened, including the full execution trace, to verify behavior or debug a failure:

```bash theme={null}
keystroke workflows runs get greeting <run-id> --include steps,trace
keystroke agents sessions get support <session-id> --include messages,trace
keystroke history list --kind workflow --status failed
```

The `--include` flag pulls in steps, messages, events, and traces so the agent has the same visibility you'd get in the web app.

## Authentication and CI

Deploying and invoking a deployed project require a one-time browser login (running a local server with `keystroke dev` needs none):

```bash theme={null}
keystroke auth login
```

The token is stored in your operating system's secure credential store and reused on every subsequent command, so an agent that runs after you've logged in can deploy and operate cloud projects without re-authenticating.

<Card title="CLI reference" href="/cli">
  Every command, flag, and the local-vs-cloud target model.
</Card>