# @standardagents/cli

CLI tool for Standard Agents setup and model discovery.

## Installation

```bash
pnpm add -D @standardagents/cli
```

## Usage

### Create And Connect A Project

```bash
npx @standardagents/cli@latest init
```

The package is published publicly so this one-liner works without a prior npm
login.

This command will:
- Open Standard Agents in your browser for login, billing, and platform repository setup
- Clone the created platform-owned Artifact repository into the directory where you ran the command
- Write `STANDARD_AGENTS_API_KEY`, `PLATFORM_ENDPOINT`, and `STANDARD_AGENTS_API_URL` to `.dev.vars`
- Configure a repo-local Git credential helper that mints short-lived Artifacts tokens through the Standard Agents platform
- Install dependencies with the detected package manager, start the local dev server in the foreground, and open the local instance

The init command stays attached to the dev server. Press Ctrl-C in that terminal to stop it.

For local platform development, point the same command at your local platform API:

```bash
STANDARD_AGENTS_API_URL=https://platform.agentbuilder-platform.orb.local pnpm exec agents init
```

When testing unreleased workspace package changes, keep the same platform flow
and add `STANDARDAGENTS_WORKSPACE=1`. With `pnpm`, the CLI rewrites the cloned
project's generated `@standardagents/*` dependencies to local workspace links
before installing, and the repo-local Git credential helper points at the
current local CLI entry instead of `npx -y @standardagents/cli@latest`. If you
are running a packed or globally installed local CLI, also set
`STANDARDAGENTS_WORKSPACE_ROOT` to the monorepo root:

```bash
STANDARDAGENTS_WORKSPACE=1 STANDARD_AGENTS_API_URL=https://platform.agentbuilder-platform.orb.local pnpm exec agents init
STANDARDAGENTS_WORKSPACE=1 STANDARDAGENTS_WORKSPACE_ROOT=/path/to/agentbuilder STANDARD_AGENTS_API_URL=https://platform.agentbuilder-platform.orb.local cli init
```

From the monorepo root, `pnpm onboarding:verify:local` runs both no-publish
verification modes against a fake platform API: the pnpm workspace-dev path and
a local-registry run of the literal `npx @standardagents/cli@latest init` shape
that serves locally packed packages in place of the unpublished npm registry
packages. Use `-- --mode=workspace` or `-- --mode=npx` when you only need one
side.

After release automation publishes the CLI and runtime packages, run
`pnpm onboarding:verify:production` to exercise the real production one-liner
against the npm registry without touching GitHub, Stripe, or the production
platform. It runs `npx @standardagents/cli@latest init` against a fake platform
API and requires the generated project to install `@standardagents/*` packages
from npm.
All Standard Agents package publishes must go through the approved release
automation. The release path publishes with public access, repairs package
visibility if a scoped version already exists, and sets the release dist-tag.
Do not run manual npm publishes to test this flow.

Use `agents init --local my-agent-project` for the legacy local-only template scaffold that does not create a platform repo or billing connection.

#### Options

- `-y, --yes` - Skip prompts and use defaults
- `--api-url <url>` - Platform API URL. Also available through `STANDARD_AGENTS_API_URL` or `PLATFORM_ENDPOINT`
- `--package-manager <manager>` - Override package manager detection (`npm`, `pnpm`, `yarn`, or `bun`)
- `--local` - Use the legacy local-only scaffold flow

Set `STANDARD_AGENTS_BROWSER="Google Chrome"` or another macOS browser app name when you need the browser handoff to use a specific browser during local development. Set `STANDARD_AGENTS_BROWSER=none` for headless verification.

### Scaffold Project Structure

```bash
pnpm exec agents scaffold
```

Adds Standard Agents to an existing Vite project. The command updates
`package.json` with the current `@standardagents/builder` version, wires the
`builder()` Vite plugin, and creates the `agents/` directory structure with
documentation files. The builder plugin generates the Cloudflare Worker entry
and binding config at build time.

### Deploy From Artifacts Git

Deployments are triggered by pushes to the platform-owned Artifacts repository:

```bash
git push origin main
# or
agents deploy
```

`agents deploy` is a convenience wrapper around `git push origin HEAD:<branch>`.
It does not run a local build or upload bundles; the platform build runner
deploys from the Artifacts push event.

### Install The AgentBuilder Skill

```bash
npx @standardagents/cli skill
```

Opens an interactive picker and installs the bundled `agentbuilder` guidance
into a supported coding agent. Right now that means:

- Codex: installs a skill folder into `$CODEX_HOME/skills` or `~/.codex/skills`
- Claude Code: installs a user subagent into `~/.claude/agents/agentbuilder.md`

Use `--force` to overwrite an existing installed copy:

```bash
npx @standardagents/cli skill --force
```

Skip the picker with an explicit target:

```bash
npx @standardagents/cli skill --agent codex
npx @standardagents/cli skill --agent claude
```

### Read The Curated Current Models Guide

```bash
pnpm exec agents current-models
```

This fetches the live markdown guide from the Standard Agents spec site and
prints it to stdout.

### List Available Models From A Configured Provider

```bash
pnpm exec agents available-models --provider=cerebras
```

The CLI reads your current project's installed provider packages plus the env
keys in `.env`, `.env.local`, `.dev.vars`, `.dev.vars.local`, and `process.env`.
If multiple providers are configured, specify one with `--provider`.

The command walks every provider page until it has the full model list, then
prints a markdown table containing the exact `model` strings to use in
`defineModel({ model: ... })`.

## Manual Configuration

For new projects, manual Cloudflare configuration is not required. Add
`builder()` to `vite.config.ts`; it injects the Cloudflare Vite plugin, Worker
entry, assets config, Durable Object bindings, Worker Loader binding,
compatibility flags, and migrations automatically.

## TypeScript Types

AgentBuilder generates project types when the dev server starts. For a focused
type-generation pass, run:

```bash
pnpm exec vite build
```

This will update your `worker-configuration.d.ts` file with:

```typescript
interface Env {
  AGENT_BUILDER_THREAD: DurableObjectNamespace<DurableThread>;
  AGENT_BUILDER: DurableObjectNamespace<DurableAgentBuilder>;
}
```