# CLI Overview

> Command-line interface for managing Struere agents

The Struere CLI is your primary interface for defining, syncing, and deploying agents and platform resources. It is built with Commander.js and ships as part of the `struere` npm package.

## Available Commands

| Command | Purpose |
|---------|---------|
| `struere init` | Initialize an organization-centric project, scaffold directories |
| `struere dev` | Watch all files, sync everything to Convex on change |
| `struere deploy` | Deploy all resources to production |
| `struere sync` | Sync resources to Convex and exit |
| `struere add <type> <name>` | Scaffold a new agent, data-type, role, automation, router, eval, or fixture |
| `struere data` | Browse and manage data records |
| `struere status` | Compare local file definitions vs remote state |
| `struere pull` | Pull remote resources to local files |
| `struere logs` | View and debug agent conversations |
| `struere docs` | Generate AI context files (CLAUDE.md, .cursorrules, copilot-instructions) from live docs |
| `struere eval run <suite>` | Run an eval suite and generate Markdown reports |
| `struere compile-prompt <slug>` | Compile and preview an agent's system prompt |
| `struere run-tool <tool> [--agent <slug>]` | Run a tool as it would execute during a real agent conversation |
| `struere chat <slug>` | Chat with an agent interactively or send a single message |
| `struere chat --router <slug>` | Chat via a router with routing rules evaluation |
| `struere diff` | Show content differences between local and remote resources |
| `struere doctor` | Run diagnostic checks on your Struere project |
| `struere keys list` | List API keys for the current org and environment |
| `struere keys create` | Create a new API key (plaintext shown once) |
| `struere keys revoke <id-or-prefix>` | Hard-delete an API key |
| `struere templates list` | List WhatsApp message templates |
| `struere templates create <name>` | Create a new message template |
| `struere templates delete <name>` | Delete a message template |
| `struere templates status <name>` | Check template approval status |
| `struere triggers` | Manage triggers and automation runs |
| `struere triggers fire <slug>` | Manually fire a trigger for testing |
| `struere integration [provider]` | Manage integrations (airtable, resend, flow) |
| `struere threads` | Manage conversation threads (list, view, archive, reset) |
| `struere whatsapp` | Manage WhatsApp connections and routing |
| `struere org list` | List your organizations |
| `struere org create [name]` | Create a new organization |
| `struere login` | Browser-based OAuth authentication |
| `struere logout` | Clear stored credentials |
| `struere whoami` | Display the current logged-in user and organization |

## Quick Start

```bash
bun add struere
bunx struere init
bunx struere dev
```

## Auto-Run Behavior

The CLI automatically handles prerequisites so you never need to run setup commands manually:

- **No `struere.json`?** — Automatically runs `init` before proceeding
- **Not logged in?** — Automatically runs `login` before proceeding
- **Stale `.struere/` shim?** — The `dev`, `sync`, `deploy`, and `status` commands auto-regenerate the `.struere/index.js`, `index.d.ts`, and `types.d.ts` virtual module files before loading resources, so you never need to manually update them when new SDK functions are added

This means running `bunx struere dev` in an empty directory will walk you through project initialization and authentication before starting the development sync.

## Configuration

### Project Configuration (`struere.json`)

Located at the root of your project, this file identifies your organization:

```json
{
  "version": "2.0",
  "organization": {
    "id": "org_abc123",
    "slug": "acme-corp",
    "name": "Acme Corp"
  }
}
```

### Credentials (`~/.struere/credentials.json`)

Authentication tokens are stored locally in your home directory. These are managed automatically by `struere login` and `struere logout`. The CLI proactively refreshes tokens 5 minutes before expiry and silently retries on auth errors, so you rarely need to re-authenticate during a session.

## Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `STRUERE_CONVEX_URL` | `your-deployment.convex.cloud` | Convex deployment URL |
| `STRUERE_API_KEY` | — | API key for production deployments |
| `STRUERE_AUTH_URL` | `app.struere.dev` | Auth callback URL for OAuth flow |

## Architecture

The CLI is organized into command files and utility modules:

```
src/cli/
├── index.ts              # Entry point, Commander.js setup, version check
├── commands/
│   ├── init.ts           # Project initialization
│   ├── dev.ts            # File watching and sync
│   ├── deploy.ts         # Production deployment
│   ├── add.ts            # Resource scaffolding
│   ├── status.ts         # Local vs remote comparison
│   ├── pull.ts           # Pull remote to local
│   ├── eval.ts           # Eval suite runner
│   ├── keys.ts           # API key management
│   ├── templates.ts      # WhatsApp template management
│   ├── org.ts            # Organization management
│   ├── compile-prompt.ts # Compile system prompt templates
│   ├── run-tool.ts       # Run tools for testing
│   ├── chat.ts           # Interactive agent chat
│   ├── logs.ts           # View and debug conversations
│   ├── docs.ts           # Generate AI context files
│   ├── triggers.ts       # Manage triggers and automation runs
│   ├── integration.ts    # Integration config management
│   ├── whatsapp.ts       # WhatsApp connection management
│   ├── login.ts          # Browser-based OAuth
│   ├── logout.ts         # Clear credentials
│   └── whoami.ts         # Current user info
└── utils/
    ├── loader.ts          # Load resources from directories
    ├── extractor.ts       # Build sync payload
    ├── project.ts         # Load/save struere.json
    ├── convex.ts          # API calls to Convex
    ├── evals.ts           # Eval API helpers
    ├── whatsapp.ts        # WhatsApp template API helpers
    ├── scaffold.ts        # File templates for new resources
    └── credentials.ts     # Auth token management
```

### Startup

On every invocation, the CLI performs a version check against npm with a 2-second timeout. If a newer version is available, it displays an update notice.

## Sync Mechanism

The CLI syncs your local definitions to the Convex backend. The sync flow is:

1. **Load** — Read all files from `agents/`, `entity-types/`, `roles/`, `triggers/`, `tools/`, `routers/`, `evals/`, and `fixtures/` directories
2. **Validate** — Check cross-resource references before syncing (router agent references, trigger entity type references, integration requirements). Errors block the sync; warnings display but allow it to continue.
3. **Extract** — Build a sync payload using `extractSyncPayload()`
4. **Sync to development** — Send agents, data types, roles, triggers, and tools to `syncOrganization`
5. **Sync to eval** — Send agents, data types, roles, tools, eval suites, and fixtures to `syncOrganization` (triggers excluded)
6. **Watch** (dev mode) — Monitor files with chokidar and re-sync on any change

Resources are upserted by slug or name, meaning the CLI handles both creation and updates transparently. Fixture sync resets the eval environment on every sync (deletes all entities/relations, then recreates from YAML).

## Organization-Centric Design

Struere uses an organization-centric architecture. A single project defines all resources for one organization:

- All agents in `agents/`
- All data types in `entity-types/`
- All roles in `roles/`
- All automations in `triggers/`
- All routers in `routers/`
- Shared custom tools in `tools/`
- Eval suites in `evals/`
- Fixture data in `fixtures/`

This means you manage your entire platform configuration from a single codebase, with the CLI handling synchronization to the backend.