diff --git a/.changeset/bootstrap-ux-3.md b/.changeset/bootstrap-ux-3.md new file mode 100644 index 0000000..cf11d3b --- /dev/null +++ b/.changeset/bootstrap-ux-3.md @@ -0,0 +1,13 @@ +--- +"@united-workforce/cli": patch +--- + +fix: improve bootstrap docs — pnpm/npm parity, adapter install order, preset provider table (#118) + +- Step 1: show pnpm and npm side-by-side (not just pnpm with a comment) +- Step 1: add "adapter must be installed before `uwf setup --agent`" note +- Step 1: add `uwf --version` and adapter version verification with PATH troubleshooting +- Step 2: `--agent` takes adapter command name (e.g. `uwf-hermes`), not npm package +- Step 2: preset providers listed as a table with names and default base URLs +- Step 2: non-preset providers must specify `--base-url` manually +- Upgrade scenario: also show npm alternatives diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts index 3ebe3b2..a2d323d 100644 --- a/packages/cli/src/commands/prompt.ts +++ b/packages/cli/src/commands/prompt.ts @@ -90,18 +90,43 @@ which hermes ### Step 1 — Install CLI and agent adapter +Install the CLI using **either** pnpm or npm: + \`\`\`bash -pnpm add -g @united-workforce/cli # or: npm install -g @united-workforce/cli -uwf --version # should print ${CLI_VERSION} +# Using pnpm (recommended) +pnpm add -g @united-workforce/cli + +# Using npm +npm install -g @united-workforce/cli \`\`\` -Install an agent adapter (at least one is required): +Next, install an agent adapter (**must be installed before running \`uwf setup --agent\`**): -| Adapter | Install | When to use | -|---------|---------|-------------| -| uwf-hermes | \`pnpm add -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent | -| uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly | -| uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) | +| Adapter | Install (pnpm / npm) | When to use | +|---------|----------------------|-------------| +| uwf-hermes | \`pnpm add -g @united-workforce/agent-hermes\` / \`npm i -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent | +| uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` / \`npm i -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly | +| uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` / \`npm i -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) | + +**After installing, verify that \`uwf\` and the adapter command (e.g. \`uwf-hermes\`) are available in PATH.** Run: + +\`\`\`bash +uwf --version # should print ${CLI_VERSION} +uwf-hermes --version # (or uwf-claude-code / uwf-builtin) +\`\`\` + +If either command is not found, the global bin directory is not in the current shell's PATH. **You must fix this before continuing:** + +1. Find where the binary was installed: + \`\`\`bash + find ~/.local ~/.hermes /usr/local -name uwf -type f 2>/dev/null + npm prefix -g # global prefix — bin is /bin + \`\`\` +2. Add the directory to PATH permanently by appending to the user's shell config (e.g. \`~/.bashrc\`, \`~/.zshrc\`, \`~/.profile\`, or fish config): + \`\`\`bash + export PATH=":$PATH" + \`\`\` +3. Source the updated config or open a new shell, then re-verify the commands work. **uwf-hermes** also requires the Hermes ACP plugin: \`\`\`bash @@ -115,18 +140,35 @@ pipx install 'hermes-agent[acp]' pip install -e '.[acp]' \`\`\` -Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose). - ### Step 2 — Configure provider and model uwf needs an LLM provider to run agents. **Ask the user** for their provider, API key, and model, then run: \`\`\`bash -uwf setup --provider --base-url --api-key --model [--agent ] +uwf setup --provider --api-key --model --agent \`\`\` -Preset providers (base-url is auto-filled when using a preset name): -openai, xai, openrouter, venice, dashscope, deepseek, siliconflow, volcengine, kimi, glm, stepfun, minimax, ollama +**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`), not the npm package name. + +**Preset providers** — when using a preset name, \`--base-url\` is auto-filled and can be omitted: + +| Provider | Name | Default base URL | +|----------|------|-----------------| +| OpenAI | \`openai\` | https://api.openai.com/v1 | +| xAI | \`xai\` | https://api.x.ai/v1 | +| OpenRouter | \`openrouter\` | https://openrouter.ai/api/v1 | +| Venice | \`venice\` | https://api.venice.ai/api/v1 | +| Dashscope | \`dashscope\` | https://dashscope.aliyuncs.com/compatible-mode/v1 | +| DeepSeek | \`deepseek\` | https://api.deepseek.com/v1 | +| SiliconFlow | \`siliconflow\` | https://api.siliconflow.cn/v1 | +| VolcEngine | \`volcengine\` | https://ark.cn-beijing.volces.com/api/v3 | +| Kimi (Moonshot) | \`kimi\` | https://api.moonshot.cn/v1 | +| GLM (Zhipu AI) | \`glm\` | https://open.bigmodel.cn/api/paas/v4 | +| StepFun | \`stepfun\` | https://api.stepfun.com/v1 | +| MiniMax | \`minimax\` | https://api.minimax.io/v1 | +| Ollama (local) | \`ollama\` | http://localhost:11434/v1 | + +For **non-preset providers**, you must specify \`--base-url\` manually. Example: \`\`\`bash @@ -196,11 +238,25 @@ If the thread reaches \`$END\` with status \`completed\`, the setup is working. ### Step 1 — Update packages \`\`\`bash -pnpm add -g @united-workforce/cli@latest # or: npm install -g @united-workforce/cli@latest -uwf --version # should print ${CLI_VERSION} +# Using pnpm +pnpm add -g @united-workforce/cli@latest -# Also update your adapter(s) +# Using npm +npm install -g @united-workforce/cli@latest +\`\`\` + +\`\`\`bash +uwf --version # should print ${CLI_VERSION} +\`\`\` + +Also update your adapter(s): + +\`\`\`bash +# pnpm pnpm add -g @united-workforce/agent-hermes@latest + +# npm +npm install -g @united-workforce/agent-hermes@latest \`\`\` ### Step 2 — Regenerate skills