|
1 | 1 | # Commands |
2 | 2 |
|
3 | | -Every command works in two modes: |
| 3 | +`setup`, `apply`, `pull`, `push`, `cleanup` and `call` work in two modes: |
4 | 4 |
|
5 | 5 | - **Interactive** — run without arguments, get prompted for org and resources |
6 | | -- **Direct** — pass an org slug and flags for scripting / CI |
7 | | - |
8 | | -| Command | Interactive | Direct | One-liner | |
9 | | -| --- | --- | --- | --- | |
10 | | -| `npm run setup` | ✅ | — | First-time org wizard — creates `.env.<org>` and `resources/<org>/`. | |
11 | | -| `npm run validate` | — | `npm run validate -- <org>` | Schema-check local YAML/MD with no network call. **Run before every `apply`.** | |
12 | | -| `npm run audit` | — | `npm run audit -- <org> [--type <t>]` | Read-only drift detector — orphan local YAML, state ghosts, UUID collisions, content-identical clusters, sibling base-slug clusters, dashboard orphans, assistants with inline `model.tools`. Exit 1 on any finding; safe to wire into CI. | |
13 | | -| `npm run promote` | — | `npm run promote -- --pipeline <name> --from <org> --to <org> [--apply]` | Plan or apply a forward-only, dependency-aware promotion defined by `promotion.yml`. | |
14 | | -| `npm run apply` | ✅ | `npm run apply -- <org> [--force]` | **Default deploy verb.** Pull → merge → push in one safe pass; resilient against dashboard drift. | |
15 | | -| `npm run pull` | ✅ | `npm run pull -- <org> [flags]` | Fetch remote state into local files / state file. Local-first by default — won't clobber local edits. | |
16 | | -| `npm run push` | ✅ | `npm run push -- <org> [flags]` | Raw push without a pre-pull. Refuses by default when local YAML files lack state entries (orphan-YAML gate); pass `--allow-new-files` to bypass after confirming intent. **Skip unless you just ran `pull` and are certain state is fresh** — otherwise prefer `apply`. | |
17 | | -| `npm run cleanup` | ✅ | `npm run cleanup -- <org> [--force --confirm <org>]` | Inspect (default) or delete orphaned remote resources. Destructive run requires `--confirm <org>`. | |
18 | | -| `npm run rollback` | — | `npm run rollback -- <org> --list` or `--to <ISO>` | Restore from a snapshot in `.vapi-state.<org>.snapshots/` (one is written before every push/apply). | |
19 | | -| `npm run call` | ✅ | `npm run call -- <org> -a <name>` or `-s <squad>` | Start an interactive WebSocket call against an assistant or squad. | |
20 | | -| `npm run sim` | — | `npm run sim -- <org> --suite <name> --target <name> [--timeout <min>]` | Run a simulation suite (or specific simulations) against a deployed assistant/squad. Prints the run link; exits 0 passed, 1 failed, 3 incomplete (timeout, Ctrl-C, missing results). | |
21 | | -| `npm run check` | — | `npm run check -- <check>\|--all [--dry-run] [--changed-since <ref>] [--budget-minutes <n>] [--json <path>]` | Run the `vapi-checks.yml` simulation checks against the files on disk: each target is built inline (tools, handoffs, judges, personalities; tools mocked fail-closed, servers dead-ended) and run in one simulation run per target, so nothing is deployed. Posts `Vapi Evals` commit statuses when run by the PR workflow. `--dry-run` builds the payloads offline (no key, nothing sent; `--print-payload` writes them). Exits 0 passed, 1 failed, 2 config or build error, 3 incomplete (timeout, interrupt, budget, billing). | |
22 | | -| `npm run migrate` | — | `npm run migrate` | One-time, all orgs at once: slim legacy state files to pure `name → uuid` and seed the per-developer `.vapi-state-hash/` baseline store from the old hashes. Required once after upgrading to the hash-store engine — `pull`/`push`/`apply` refuse legacy-shaped state until it runs. Idempotent. | |
23 | | -| `npm run build` | — | — | Type-check the codebase (`tsc --noEmit`). | |
24 | | -| `npm test` | — | — | Run regression tests (`node:test`). | |
| 6 | +- **Direct** — pass an org name and flags, for scripts and CI |
| 7 | + |
| 8 | +The other commands are direct only. |
| 9 | + |
| 10 | +| Command | Usage | What it does | |
| 11 | +| --- | --- | --- | |
| 12 | +| `npm run setup` | `npm run setup [-- <org>]` | Connect an org: creates `.env.<org>` and `resources/<org>/`. | |
| 13 | +| `npm run validate` | `npm run validate -- <org>` | Check resource files offline. Run it before every `apply`. | |
| 14 | +| `npm run apply` | `npm run apply -- <org> [types or paths]` | **The default deploy:** pull, merge, then push. See [workflows](workflows.md). | |
| 15 | +| `npm run pull` | `npm run pull -- <org> [--force] [--bootstrap]` | Sync platform changes down; never overwrites local edits unless `--force`. | |
| 16 | +| `npm run push` | `npm run push -- <org> [--dry-run]` | Push without pulling first. Prefer `apply`. | |
| 17 | +| `npm run rollback` | `npm run rollback -- <org> --list` or `--to <ISO>` | Restore a pre-deploy snapshot from `.vapi-state.<org>.snapshots/`. | |
| 18 | +| `npm run cleanup` | `npm run cleanup -- <org> [--force --confirm <org>]` | List platform resources with no file; delete them only with both flags. | |
| 19 | +| `npm run audit` | `npm run audit -- <org> [--type <type>]` | Report drift between files, state and the platform. Exits 1 on any finding, so it can run in CI. | |
| 20 | +| `npm run call` | `npm run call -- <org> -a <assistant>` or `-s <squad>` | Talk to an assistant or squad from your terminal. | |
| 21 | +| `npm run sim` | `npm run sim -- <org> --suite <name> --target <name>` | Run a simulation suite against deployed resources. Exits 0 passed, 1 failed, 3 incomplete. | |
| 22 | +| `npm run check` | `npm run check -- <check>` or `--all`, `[--dry-run]` | Run [PR checks](pr-checks.md) against local files, nothing deployed. Exits 0 passed, 1 failed, 2 config or build error, 3 incomplete. | |
| 23 | +| `npm run promote` | `npm run promote -- --pipeline <p> --from <org> --to <org> [--apply]` | Plan, or apply, a [promotion](promotion.md) between orgs. | |
| 24 | +| `npm run build` | `npm run build` | Type-check the code and tests. | |
| 25 | +| `npm test` | `npm test` | Run the test suite. | |
25 | 26 |
|
26 | 27 | ## Interactive Mode |
27 | 28 |
|
@@ -86,3 +87,17 @@ npm run call -- my-org -a my-assistant |
86 | 87 | # Call a squad |
87 | 88 | npm run call -- my-org -s my-squad |
88 | 89 | ``` |
| 90 | + |
| 91 | +## Upgrading from an older version |
| 92 | + |
| 93 | +Repositories created before the state-file format changed need a one-time |
| 94 | +migration. `pull`, `push` and `apply` refuse to run until it's done: |
| 95 | + |
| 96 | +```bash |
| 97 | +npm run migrate |
| 98 | +``` |
| 99 | + |
| 100 | +It rewrites every org's `.vapi-state.<org>.json` to the current |
| 101 | +`{ "name": { "uuid": … } }` format and seeds your local |
| 102 | +`.vapi-state-hash/` drift baseline from the old file. It's safe to run more |
| 103 | +than once. Commit the rewritten state files. |
0 commit comments