@swarmcraftai/cli 0.5.0 → 0.6.0
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.
- package/CHANGELOG.md +14 -0
- package/README.md +104 -125
- package/dist/main.cjs +550 -453
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to the SwarmCraft CLI are documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.6.0
|
|
6
|
+
|
|
7
|
+
- Adds Claude Code subscription support to repository bootstrap, Operate, and one-shot, with generated `.claude/skills` and owner-preserving `CLAUDE.md` guidance.
|
|
8
|
+
- Checks local Claude subscription login, preserves macOS login discovery, and rejects API credential injection on that path.
|
|
9
|
+
- Preserves blocked run state after provider failures and supports do/check through human review and resume.
|
|
10
|
+
- Refreshes installation, native Windows, provider setup, permissions, and recovery instructions.
|
|
11
|
+
- Requires the coordinated API update for Claude Operate telemetry; deploy the API before this client.
|
|
12
|
+
|
|
13
|
+
## 0.5.1
|
|
14
|
+
|
|
15
|
+
- Refreshes the npm README around customer installation and common workflows, with native PowerShell commands, Node/npm verification, managed-machine recovery and VS Code restart guidance.
|
|
16
|
+
- Clarifies that WSL is not required for the SwarmCraft CLI and that AI-provider prerequisites are separate.
|
|
17
|
+
- Command behavior and the editor/Setup capability contract remain unchanged from 0.5.0.
|
|
18
|
+
|
|
5
19
|
## 0.5.0
|
|
6
20
|
|
|
7
21
|
- Adds deterministic `operate init`, `operate validate`, and `operate status` commands for local operational work, with Codex and Copilot guidance for Work, Automate, and Formalise.
|
package/README.md
CHANGED
|
@@ -1,190 +1,169 @@
|
|
|
1
1
|
# SwarmCraft CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[SwarmCraft](https://swarmcraft.ai) helps you use AI to get operational work done, automate repeatable tasks, and build applications. It gives your AI assistant shared skills and structured workflows while you keep control of your knowledge, records, and code.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The CLI brings SwarmCraft workflows to your terminal. Use it to prepare a local repository for operational work or run implementation tasks from your SwarmCraft project board with an AI coding agent. You can inspect progress, resume interrupted runs, and collect support diagnostics.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Prerequisites
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
- Node.js 20.19 or newer, npm, and Git.
|
|
10
|
+
- A SwarmCraft account and a project with tasks ready to implement.
|
|
11
|
+
- A local Git repository with unrelated changes committed or stashed.
|
|
12
|
+
- Codex CLI, GitHub Copilot CLI, or Claude Code CLI installed and configured, or SwarmCraft Managed AI credits.
|
|
10
13
|
|
|
11
|
-
|
|
14
|
+
On macOS and Windows, start with [SwarmCraft Setup](https://swarmcraft.ai/docs/set-up-and-connect/use-swarmcraft-setup) to prepare your environment.
|
|
12
15
|
|
|
13
|
-
##
|
|
14
|
-
|
|
15
|
-
- Package name: `@swarmcraftai/cli`
|
|
16
|
-
- Installed command: `swarmcraft`
|
|
17
|
-
- Supported runtime target: Node.js 20.19 or newer
|
|
18
|
-
- Local run artifact location: `.swarmcraft/runs/<run-id>` inside the selected customer workspace
|
|
19
|
-
- Public package contents: bundled CLI runtime, README, package metadata, and license
|
|
20
|
-
- Shared workspace packages are bundled into the CLI artifact; customers do not install `@swarmcraft/packet-workflow` or `@swarmcraft/repo-seed` directly.
|
|
21
|
-
|
|
22
|
-
## Implemented Module Ownership
|
|
23
|
-
|
|
24
|
-
- `src/main.ts` is the executable composition root: it dispatches parsed commands, prompts where compatibility requires it, prints outcomes, and selects exit behavior.
|
|
25
|
-
- `src/commands/command-catalog.ts` owns stable command names, usage text, and help lookup; `src/commands/arguments.ts` owns syntax-only argument parsing and repeated option access.
|
|
26
|
-
- `src/apiClient.ts` maps API transport contracts; `src/sessionStore.ts` is the only owner of the owner-only local credential file.
|
|
27
|
-
- `src/workspace.ts` owns workspace validation and contained file/git operations. `src/runtime/workspace-paths.ts` rejects absolute, traversal, escaped run, manifest, log, and support-artifact targets.
|
|
28
|
-
- `src/runtime/process.ts` provides shell-free argument-array execution. Only `runTrustedShellAgentCommand` may invoke a shell for a deliberately supplied custom-agent template; API content and credentials must never be interpolated into it.
|
|
29
|
-
- `src/bootstrap.ts`, `src/discovery.ts`, and `src/oneShot.ts` compose the seed, immutable discovery-package, and packet execution workflows.
|
|
30
|
-
- `src/operation/` owns Operate filesystem/Git preflight, shared-seed reconciliation, local inspection, and content-safe status; `src/commands/operate-commands.ts` owns its session validation, cancellation, output, and exit codes.
|
|
31
|
-
- `src/workflows/agent-execution.ts` owns approved credential injection, trusted template quoting, and optional cost capture. `src/artifacts/run-manifest.ts` owns contained paths and atomic resume-manifest persistence.
|
|
32
|
-
- `src/supportBundle.ts` exposes only allow-listed delegation facts and recursively redacts secret-bearing keys.
|
|
33
|
-
|
|
34
|
-
All customer run artifacts remain below `.swarmcraft/runs/<run-id>`. Workspace-relative reads, writes, removals, packet paths, discovery sources, logs, manifests, diagnostics, and support bundles are resolved through the containment boundary before access.
|
|
35
|
-
|
|
36
|
-
## Distribution
|
|
37
|
-
|
|
38
|
-
The first public distribution channel is npm:
|
|
16
|
+
## Install
|
|
39
17
|
|
|
40
18
|
```bash
|
|
41
19
|
npm install -g @swarmcraftai/cli
|
|
42
20
|
swarmcraft --help
|
|
43
21
|
```
|
|
44
22
|
|
|
45
|
-
|
|
23
|
+
For one-off use, run `npx @swarmcraftai/cli --help`.
|
|
46
24
|
|
|
47
|
-
|
|
48
|
-
npx @swarmcraftai/cli --help
|
|
49
|
-
```
|
|
25
|
+
## Native Windows installation
|
|
50
26
|
|
|
51
|
-
|
|
27
|
+
WSL is not required for the SwarmCraft CLI. In PowerShell:
|
|
52
28
|
|
|
53
|
-
```
|
|
54
|
-
|
|
29
|
+
```powershell
|
|
30
|
+
node --version
|
|
31
|
+
npm.cmd --version
|
|
32
|
+
npm.cmd install -g @swarmcraftai/cli
|
|
33
|
+
swarmcraft.cmd --version
|
|
34
|
+
swarmcraft.cmd operate init --help
|
|
35
|
+
Get-Command node, npm.cmd, swarmcraft.cmd
|
|
36
|
+
npm.cmd prefix -g
|
|
55
37
|
```
|
|
56
38
|
|
|
57
|
-
|
|
39
|
+
Use a supported Node.js LTS release meeting the minimum above. Confirm the npm global prefix is on your user PATH, then fully quit and reopen VS Code. A window reload may retain the old PATH. Use `.cmd` commands instead of changing PowerShell execution policy. If software installation or the prefix is restricted, use your organisation's approved installation or user-writable prefix; preserve managed runtimes and npm registry/authentication settings.
|
|
58
40
|
|
|
59
|
-
|
|
41
|
+
The extension needs an installed CLI; one-off `npx` execution does not satisfy that requirement. See the [manual setup checklist](https://swarmcraft.ai/docs/set-up-and-connect/manual-setup-checklist). AI providers have separate platform and authentication requirements.
|
|
60
42
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
43
|
+
PowerShell uses different line continuation from Bash. Run the multiline examples below on one line, using `swarmcraft.cmd`, for example:
|
|
44
|
+
|
|
45
|
+
```powershell
|
|
46
|
+
swarmcraft.cmd one-shot --project YOUR_PROJECT_ID --workspace . --agent-provider codex --task-limit 1 --max-agent-requests 100 --commit-policy done
|
|
64
47
|
```
|
|
65
48
|
|
|
66
|
-
|
|
49
|
+
## Run your first task
|
|
50
|
+
|
|
51
|
+
Sign in and find your project ID:
|
|
67
52
|
|
|
68
53
|
```bash
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
pnpm release:smoke
|
|
54
|
+
swarmcraft auth login --email you@example.com
|
|
55
|
+
swarmcraft projects list
|
|
72
56
|
```
|
|
73
57
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
## Current Commands
|
|
58
|
+
Login prompts for your password and any required verification code. Your CLI session is saved in `~/.swarmcraft/cli-session.json`; keep this file private.
|
|
77
59
|
|
|
78
|
-
|
|
60
|
+
From your project's local Git repository, check your setup:
|
|
79
61
|
|
|
80
62
|
```bash
|
|
81
|
-
swarmcraft
|
|
82
|
-
swarmcraft delegation start --user <customer-email-or-id> --reason <text> --expires-in-minutes 600
|
|
83
|
-
swarmcraft projects list --delegation <delegation-id>
|
|
84
|
-
swarmcraft discovery prepare --workspace <path>
|
|
85
|
-
swarmcraft discovery validate --workspace <path>
|
|
86
|
-
swarmcraft discovery support-bundle --workspace <path> --run <run-id>
|
|
87
|
-
swarmcraft init --project <project-id> --workspace <path> --agent-provider codex --delegation <delegation-id>
|
|
88
|
-
swarmcraft one-shot --project <project-id> --workspace <path> --agent-provider codex --delegation <delegation-id>
|
|
89
|
-
swarmcraft one-shot --project <project-id> --workspace <path> --agent-provider codex --run-id <known-run-id>
|
|
90
|
-
swarmcraft resume --run <run-id> --workspace <path> --delegation <delegation-id>
|
|
91
|
-
swarmcraft status --run <run-id> --workspace <path> --delegation <delegation-id>
|
|
92
|
-
swarmcraft delegation end --delegation <delegation-id>
|
|
63
|
+
swarmcraft doctor --workspace . --agent-provider codex
|
|
93
64
|
```
|
|
94
65
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
Operate is a starting path for operational work, not a third application-generation route. The seeded `swarmcraft-work` skill completes useful work and maintains terminology, knowledge, systems, and domain records. `swarmcraft-automate` considers bounded repeatability, including after one suitable task; `swarmcraft-formalise` prepares a reviewed application opportunity. Seeding all three does not execute them, approve automation, upload evidence, or transfer record ownership to a generated app.
|
|
66
|
+
Replace `<project-id>` with an ID from the project list, then run one task:
|
|
98
67
|
|
|
99
68
|
```bash
|
|
100
|
-
swarmcraft
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
69
|
+
swarmcraft one-shot \
|
|
70
|
+
--project <project-id> \
|
|
71
|
+
--workspace . \
|
|
72
|
+
--agent-provider codex \
|
|
73
|
+
--task-limit 1 \
|
|
74
|
+
--max-agent-requests 100 \
|
|
75
|
+
--commit-policy done
|
|
105
76
|
```
|
|
106
77
|
|
|
107
|
-
|
|
78
|
+
This prepares repository guidance and task files, runs the agent, and syncs task updates to SwarmCraft. Accepted tasks move to `done`; `--commit-policy done` creates a local commit for each completed task. Omit that option to leave changes uncommitted. Review the resulting changes before sharing them.
|
|
108
79
|
|
|
109
|
-
|
|
80
|
+
The CLI refuses a dirty workspace by default. Use `--allow-dirty` only when you intend to include existing local changes in the run. The request limit bounds agent calls, not monetary cost.
|
|
110
81
|
|
|
111
|
-
|
|
82
|
+
For preparation without running an agent:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
swarmcraft init --project <project-id> --workspace . --agent-provider codex
|
|
86
|
+
```
|
|
112
87
|
|
|
113
|
-
|
|
88
|
+
`init` writes guidance and task files for review and leaves those changes uncommitted. Commit or otherwise resolve them before starting a run that requires a clean workspace. Updates preserve your edits to generated guidance and report conflicts that need attention.
|
|
114
89
|
|
|
115
|
-
|
|
90
|
+
## Choose an agent
|
|
116
91
|
|
|
117
|
-
|
|
92
|
+
- **Claude Code subscription:** use `--agent-provider claude` after local Claude sign-in.
|
|
93
|
+
- **Codex:** use `--agent-provider codex`.
|
|
94
|
+
- **GitHub Copilot:** use `--agent-provider copilot`.
|
|
95
|
+
- **SwarmCraft Managed AI:** use `--agent-provider managed` with `one-shot`. The CLI shows your credit balance and an estimated stage range before starting. If credits run out, add credits and resume the blocked run.
|
|
96
|
+
- **Custom commands and local models:** `--agent-command` overrides the provider command and supports models available through your agent, including local models. The template is executed through a shell, so use only commands you trust. Keep secrets out of command text; use `--agent-env-file` with `--agent-api-key-env-name` for provider credentials.
|
|
118
97
|
|
|
119
|
-
|
|
98
|
+
Codex, Copilot, Claude Code, and custom providers use your own provider setup and are outside the Managed AI fee.
|
|
120
99
|
|
|
121
|
-
|
|
100
|
+
## Inspect and resume work
|
|
122
101
|
|
|
123
|
-
|
|
102
|
+
Use the run ID printed by the CLI:
|
|
124
103
|
|
|
125
104
|
```bash
|
|
126
|
-
swarmcraft
|
|
127
|
-
|
|
128
|
-
--workspace <path> \
|
|
129
|
-
--agent-provider copilot \
|
|
130
|
-
--agent-command 'COPILOT_PROVIDER_BASE_URL=http://localhost:11434/v1 COPILOT_MODEL=qwen3-coder:30b COPILOT_OFFLINE=true copilot --allow-all-tools --no-ask-user -p {command}' \
|
|
131
|
-
--task-limit 1 \
|
|
132
|
-
--max-agent-requests 1
|
|
105
|
+
swarmcraft status --run <run-id> --workspace .
|
|
106
|
+
swarmcraft resume --run <run-id> --workspace .
|
|
133
107
|
```
|
|
134
108
|
|
|
135
|
-
Run
|
|
109
|
+
Run records and agent logs are stored in `.swarmcraft/runs/<run-id>/`, including `manifest.json` and the `logs/` directory. Treat these files as potentially sensitive.
|
|
110
|
+
|
|
111
|
+
If a run reached its request limit, raise the total ceiling when resuming:
|
|
136
112
|
|
|
137
113
|
```bash
|
|
138
|
-
swarmcraft
|
|
139
|
-
--project <project-id> \
|
|
140
|
-
--workspace <path> \
|
|
141
|
-
--agent-provider codex \
|
|
142
|
-
--agent-command 'codex exec --sandbox workspace-write --oss --local-provider ollama --model qwen3-coder:30b {command}' \
|
|
143
|
-
--task-limit 1 \
|
|
144
|
-
--max-agent-requests 1
|
|
114
|
+
swarmcraft resume --run <run-id> --workspace . --max-agent-requests 200
|
|
145
115
|
```
|
|
146
116
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
## Command Workflows
|
|
150
|
-
|
|
151
|
-
SwarmCraft Setup is the supported macOS and Windows foundation path before using this experienced terminal client. Interactive CLI login remains the explicit AAA V2 email fallback: it conceals password input, prompts for optional policy-required TOTP step-up, and keeps the restricted recovery-code path out of command history. GitHub, Google, and passkey sign-in remain browser-owned web and VS Code flows.
|
|
117
|
+
## Other workflows
|
|
152
118
|
|
|
153
|
-
|
|
119
|
+
For local operational work, initialize Work, Automate, and Formalise skills:
|
|
154
120
|
|
|
155
|
-
|
|
121
|
+
```bash
|
|
122
|
+
swarmcraft operate init --workspace /path/to/repository --agent-provider codex
|
|
123
|
+
swarmcraft operate validate --workspace /path/to/repository
|
|
124
|
+
swarmcraft operate status --workspace /path/to/repository
|
|
125
|
+
```
|
|
156
126
|
|
|
157
|
-
|
|
127
|
+
Use `--adopt` to initialize an existing nonempty repository. Initialization previews the files and creates a local commit containing the seed changes. It preserves owner edits and does not push or run an agent. Validation and status work offline; both accept `--json`.
|
|
158
128
|
|
|
159
|
-
|
|
129
|
+
For a workspace that has completed [Deep Discovery review](https://swarmcraft.ai/docs/discover-and-plan/complete-deep-discovery), prepare and validate its package:
|
|
160
130
|
|
|
161
|
-
|
|
131
|
+
```bash
|
|
132
|
+
swarmcraft discovery prepare --workspace .
|
|
133
|
+
swarmcraft discovery validate --workspace .
|
|
134
|
+
```
|
|
162
135
|
|
|
163
|
-
|
|
136
|
+
Preparation requires reviewed discovery documents and confirmed source selections. It creates a local package and a preview of the selected content; upload requires separate consent. If review or source checks fail, correct the reported issue and prepare again.
|
|
164
137
|
|
|
165
|
-
|
|
138
|
+
## Help and troubleshooting
|
|
166
139
|
|
|
167
|
-
|
|
140
|
+
```bash
|
|
141
|
+
swarmcraft --help
|
|
142
|
+
swarmcraft one-shot --help
|
|
143
|
+
swarmcraft doctor --workspace . --agent-provider codex
|
|
144
|
+
swarmcraft support-bundle --run <run-id> --workspace .
|
|
145
|
+
```
|
|
168
146
|
|
|
169
|
-
|
|
147
|
+
Run `swarmcraft auth login` again if your session has expired. For Discovery diagnostics, use `swarmcraft discovery support-bundle --workspace . --run <run-id>`.
|
|
170
148
|
|
|
171
|
-
|
|
172
|
-
credit balance and estimated stage range before starting, then consumes measured credits one
|
|
173
|
-
provider call at a time. Provider credentials, model selection, prices, and settlement remain on
|
|
174
|
-
the API; prompts, repository source, and provider responses are not written to billing records.
|
|
175
|
-
If the next bounded call cannot be funded, the local run is marked blocked and can be resumed
|
|
176
|
-
after credits are added. Codex, Copilot, and custom customer-supplied providers remain outside
|
|
177
|
-
the Managed AI fee.
|
|
149
|
+
Support bundles redact credentials; Discovery bundles exclude source and package content. Review any diagnostic files before sharing them.
|
|
178
150
|
|
|
179
|
-
|
|
151
|
+
See the [one-shot walkthrough](https://swarmcraft.ai/docs/build-and-ship/deliver-with-the-one-shot-cli), [troubleshooting guide](https://swarmcraft.ai/docs/help-and-reference/troubleshoot-swarmcraft), or [contact support](https://swarmcraft.ai/login?next=%2Fapp%2Fsupport).
|
|
180
152
|
|
|
181
|
-
|
|
153
|
+
### Claude Code subscription runs
|
|
182
154
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
```
|
|
155
|
+
Select `--agent-provider claude` for bootstrap, Operate, or one-shot. Install the
|
|
156
|
+
standalone Claude Code CLI, run `claude auth login`, and confirm subscription
|
|
157
|
+
usage in `/status`. The VS Code extension alone does not install the terminal
|
|
158
|
+
command. SwarmCraft checks the effective `claude.ai` login without retaining
|
|
159
|
+
its output and rejects provider credential flags on this subscription path.
|
|
189
160
|
|
|
190
|
-
|
|
161
|
+
One-shot invokes `/swarmcraft-do` and `/swarmcraft-check` with `dontAsk`:
|
|
162
|
+
configure the necessary tool permissions in Claude before running; unapproved
|
|
163
|
+
tools are denied. The default never enables permission bypass or API-only bare
|
|
164
|
+
mode. Claude keeps ownership of login storage and sandbox settings. Use
|
|
165
|
+
`--max-agent-requests` to bound invocations; subscription limits still apply.
|
|
166
|
+
Cost telemetry remains unknown unless an explicit adapter supplies it; required
|
|
167
|
+
cost telemetry fails when absent. Dollar estimates are not subscription bills.
|
|
168
|
+
After correcting login, permissions, or a usage limit, resume the recorded run.
|
|
169
|
+
Live subscription/platform verification is tracked in the implementation plan.
|