Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(cli): one-flag installs like `npx three-ws --claude` that never write an API key into a client config

nirholas9bef13f8096b
diff --git a/packages/three-ws-cli/src/claude-skills.js b/packages/three-ws-cli/src/claude-skills.js
new file mode 100644
index 000000000..e1d817a29
--- /dev/null
+++ b/packages/three-ws-cli/src/claude-skills.js
@@ -0,0 +1,35 @@
+// Install the three.ws skill into Claude Code: ~/.claude/skills/three-ws/SKILL.md
+// (or ./.claude/skills/ with --project). The content is the hosted entry-point
+// skill at {origin}/skill.md, so it is exactly what the site documents.
+// Idempotent: an identical file is left untouched, a changed one is replaced
+// atomically.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { request } from './http.js';
+import { systemEnv } from './paths.js';
+
+export function claudeSkillPath(env = systemEnv(), { project = false } = {}) {
+ return path.join(project ? env.cwd : env.home, '.claude', 'skills', 'three-ws', 'SKILL.md');
+}
+
+/** Returns { file, changed, error }. Never throws. */
+export async function installClaudeSkills({ origin, env = systemEnv(), project = false }) {
+ const file = claudeSkillPath(env, { project });
+ try {
+ const res = await request(`${origin}/skill.md`, { headers: { accept: 'text/markdown, text/plain' } });
+ if (!res.ok) return { file, changed: false, error: `${origin}/skill.md answered ${res.status}` };
+ const body = await res.text();
+ if (!/^---\r?\nname:\s*three-ws/m.test(body)) return { file, changed: false, error: `${origin}/skill.md is not a three.ws skill file` };
+ let current = null;
+ try { current = fs.readFileSync(file, 'utf8'); } catch { current = null; }
+ if (current === body) return { file, changed: false, error: null };
+ fs.mkdirSync(path.dirname(file), { recursive: true });
+ const tmp = `${file}.${process.pid}.tmp`;
+ fs.writeFileSync(tmp, body);
+ fs.renameSync(tmp, file);
+ return { file, changed: true, error: null };
+ } catch (err) {
+ return { file, changed: false, error: err.message };
+ }
+}
diff --git a/packages/three-ws-cli/src/cli.js b/packages/three-ws-cli/src/cli.js
index c7927a6cd..5de922e7d 100755
--- a/packages/three-ws-cli/src/cli.js
+++ b/packages/three-ws-cli/src/cli.js
@@ -10,6 +10,7 @@ import { readStore, resolveOrigin } from './store.js';
import { VERSION, ApiError } from './http.js';
import { c, errorLine, line, printJson } from './ui.js';
import { CancelledError } from './commands/common.js';
+import { clientsFromFlags } from './commands/quick.js';
export const HELP = `${c.bold('three-ws')} ${c.dim(`v${VERSION}`)}: connect any MCP client to three.ws
@@ -20,9 +21,12 @@ ${c.bold('Commands')}
setup Sign in, write the three.ws MCP servers into your clients, verify with tools/list
login Sign in or switch accounts (OAuth by default)
logout Remove stored credentials and revoke the OAuth refresh token
+ doctor Diagnose a broken setup: bad config, expired sign-in, unreachable server
status Account, plan, wallet balance, token expiry, and every configured client
whoami Print the signed-in account
create [name] Create an agent with its own Solana wallet and a public page
+ agent status [id] Live state of your agents: wallet balance, page, body
+ team [status <id>] Your specialist teams: roster, findings, last error
launch Fill in a coin for one of your agents, then review and sign it on three.ws/launch
tools Choose which tool groups each server exposes (financial tools are off by default)
mcp list Show three.ws servers configured in each client (--available lists all servers)
@@ -43,6 +47,10 @@ ${c.bold('Sign-in options')} (setup, login)
--key [sk_live_...] Use an API key (or set THREE_WS_API_KEY)
--financial Also request the scopes that let tools spend from your agent wallet
+${c.bold('One flag per client')} (whole setup, no prompts, no secrets in the client's config)
+ --claude --cursor --codex --vscode --windsurf --gemini --bob --hermes
+ e.g. npx three-ws --claude; Claude Code also gets the three.ws skill
+
${c.bold('Setup options')}
--clients a,b claude-code, claude-desktop, cursor, windsurf, vscode, bob, codex, gemini, hermes, grok-bot, print
--connector-key With grok-bot: mint a spend-free API key for Grok Bot's Bot secret
@@ -114,6 +122,14 @@ const OPTIONS = {
symbol: { type: 'string' },
image: { type: 'string' },
'initial-buy': { type: 'string' },
+ claude: { type: 'boolean' },
+ cursor: { type: 'boolean' },
+ codex: { type: 'boolean' },
+ vscode: { type: 'boolean' },
+ windsurf: { type: 'boolean' },
+ gemini: { type: 'boolean' },
+ bob: { type: 'boolean' },
+ hermes: { type: 'boolean' },
};
// `--key` alone (no value) means "prompt for it"; parseArgs needs a value for a
@@ -125,7 +141,11 @@ function normalizeArgv(argv) {
export function parse(argv) {
const { values, positionals } = parseArgs({ args: normalizeArgv(argv), options: OPTIONS, allowPositionals: true, strict: true });
if (values.client && !values.clients) values.clients = values.client;
- const [command = values.version ? 'version' : 'help', ...rest] = positionals;
+ const perClient = clientsFromFlags(values).length > 0;
+ // A per-client flag with no command is the whole setup for that client.
+ const fallback = values.version ? 'version' : perClient ? 'quick' : 'help';
+ let [command = fallback, ...rest] = positionals;
+ if (perClient && command === 'setup') command = 'quick';
return { command, positionals: rest, flags: values };
}
@@ -136,6 +156,17 @@ const COMMANDS = {
status: async (ctx) => (await import('./commands/account.js')).status(ctx),
whoami: async (ctx) => (await import('./commands/account.js')).whoami(ctx),
tools: async (ctx) => (await import('./commands/tools.js')).tools(ctx),
+ quick: async (ctx) => (await import('./commands/quick.js')).quick(ctx),
+ doctor: async (ctx) => (await import('./commands/doctor.js')).doctor(ctx),
+ team: async (ctx) => (await import('./commands/live.js')).team(ctx),
+ agent: async (ctx) => {
+ const [sub, ...rest] = ctx.positionals;
+ const next = { ...ctx, positionals: rest };
+ if (sub === 'status') return (await import('./commands/live.js')).agentStatus(next);
+ if (sub === 'create') return (await import('./commands/agent.js')).create(next);
+ if (sub === 'launch') return (await import('./commands/agent.js')).launch(next);
+ throw new Error('usage: three-ws agent <status [id]|create [name]|launch>');
+ },
create: async (ctx) => (await import('./commands/agent.js')).create(ctx),
launch: async (ctx) => (await import('./commands/agent.js')).launch(ctx),
mcp: async (ctx) => (await import('./commands/mcp.js')).mcp(ctx),
diff --git a/packages/three-ws-cli/src/commands/doctor.js b/packages/three-ws-cli/src/commands/doctor.js
new file mode 100644
index 000000000..25b5d7066
--- /dev/null
+++ b/packages/three-ws-cli/src/commands/doctor.js
@@ -0,0 +1,173 @@
+// `three-ws doctor`: diagnose a broken setup and say how to fix each finding.
+//
+// Checks, in order: Node version, the credential file (present, valid, owner-only),
+// the sign-in (expired, revoked, refreshable), every client config (parses, has a
+// three.ws entry, launcher exists, no secret written in plain text), and whether
+// each configured server answers a live tools/list. Exit 0 when nothing failed,
+// 1 otherwise; warnings alone do not fail.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, line, sym, printJson, tildify } from '../ui.js';
+import { readStore } from '../store.js';
+import { credentialsPath } from '../paths.js';
+import { bearerFor } from '../oauth.js';
+import { currentIdentity } from '../auth.js';
+import { listTools } from '../mcp-http.js';
+import { request } from '../http.js';
+import { scanClients } from './account.js';
+
+const MIN_NODE = [20, 12];
+const SECRET_RE = /sk_(live|test)_[A-Za-z0-9_-]{8,}|Bearer\s+[A-Za-z0-9._~+/-]{20,}/;
+
+const ok = (id, title, detail = '') => ({ id, status: 'ok', title, detail });
+const warn = (id, title, detail, fix) => ({ id, status: 'warn', title, detail, fix });
+const fail = (id, title, detail, fix) => ({ id, status: 'fail', title, detail, fix });
+
+export function checkNode(version = process.versions.node) {
+ const [maj, min] = version.split('.').map(Number);
+ if (maj > MIN_NODE[0] || (maj === MIN_NODE[0] && min >= MIN_NODE[1])) return ok('node', `Node.js ${version}`);
+ return fail('node', `Node.js ${version} is too old`, `three-ws needs ${MIN_NODE.join('.')} or newer.`, 'Install a current LTS from https://nodejs.org and run the command again.');
+}
+
+export function checkStoreFile(env) {
+ const file = credentialsPath(env);
+ let stat;
+ try {
+ stat = fs.statSync(file);
+ } catch {
+ return { check: warn('credentials', 'No credential file', `${tildify(file)} does not exist.`, 'Run `npx three-ws login`.'), store: null };
+ }
+ let store;
+ try {
+ store = readStore(env);
+ } catch (err) {
+ return { check: fail('credentials', 'Credential file is unreadable', err.message, `Delete ${tildify(file)} and run \`npx three-ws login\`.`), store: null };
+ }
+ if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) {
+ return { check: warn('credentials', 'Credential file is readable by other users', `${tildify(file)} has mode ${(stat.mode & 0o777).toString(8)}.`, `chmod 600 ${tildify(file)}`), store };
+ }
+ return { check: ok('credentials', 'Credential file is owner-only', tildify(file)), store };
+}
+
+async function checkAuth({ env, origin, store }) {
+ if (!store?.auth) return fail('auth', 'Not signed in', 'No credential is stored.', 'Run `npx three-ws login` (add `--device` over SSH).');
+ try {
+ const me = await currentIdentity({ origin, env });
+ if (!me) return fail('auth', 'Not signed in', 'No credential is stored.', 'Run `npx three-ws login`.');
+ const kind = store.auth.type === 'apikey' ? 'API key' : 'OAuth session';
+ return ok('auth', `Signed in as ${me.user.email || me.user.id}`, kind);
+ } catch (err) {
+ const expired = err.code === 'login_required' || err.status === 401 || err.status === 400;
+ if (expired) return fail('auth', 'Sign-in expired or revoked', err.message, 'Run `npx three-ws login` to sign in again.');
+ return warn('auth', 'Could not verify the sign-in', err.message, 'Check your network, then run `npx three-ws status`.');
+ }
+}
+
+function commandOnPath(command, env) {
+ if (path.isAbsolute(command)) return fs.existsSync(command);
+ const exts = process.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : [''];
+ for (const dir of String(env.vars.PATH || '').split(path.delimiter).filter(Boolean)) {
+ for (const ext of exts) {
+ try { fs.accessSync(path.join(dir, command + ext), fs.constants.X_OK); return true; } catch { /* keep looking */ }
+ }
+ }
+ return false;
+}
+
+/** The hosted URL an entry talks to, direct or through the proxy. */
+export function entryUrl(entry) {
+ const direct = entry.url || entry.httpUrl || entry.serverUrl;
+ if (direct) return direct;
+ const args = Array.isArray(entry.args) ? entry.args : [];
+ const i = args.indexOf('proxy');
+ return i >= 0 && /^https?:/.test(args[i + 1] || '') ? args[i + 1] : null;
+}
+
+function checkClients({ env, origin }) {
+ const out = [];
+ const urls = new Map();
+ let configured = 0;
+ for (const x of scanClients(env, origin)) {
+ const label = x.client.label;
+ if (x.error) {
+ out.push(fail(`client:${x.client.id}`, `${label} config is broken`, x.error, 'Fix or remove the file named above (a `.three-ws.bak` copy sits beside it if we edited it), then run `npx three-ws setup`.'));
+ continue;
+ }
+ if (!x.entries.length) {
+ if (x.detected) out.push(warn(`client:${x.client.id}`, `${label} is installed but has no three.ws server`, '', `Run \`npx three-ws setup --clients ${x.client.id}\`.`));
+ continue;
+ }
+ configured += 1;
+ out.push(ok(`client:${x.client.id}`, `${label}: ${x.entries.map((e) => e.name).join(', ')}`, x.files.map(tildify).join(', ')));
+ for (const { name, entry } of x.entries) {
+ if (SECRET_RE.test(JSON.stringify(entry))) {
+ out.push(warn(`secret:${x.client.id}:${name}`, `${label} / ${name} holds a secret in plain text`, 'The config file contains an API key or token.', `Rewrite it without one: \`npx three-ws setup --clients ${x.client.id} --proxy\`, then rotate the key on /dashboard/api if the file was shared.`));
+ }
+ if (entry.command && !commandOnPath(entry.command, env)) {
+ out.push(fail(`launcher:${x.client.id}:${name}`, `${label} / ${name} launches \`${entry.command}\`, which is not on PATH`, '', 'Install Node.js (it provides npx), restart the client, or rerun `npx three-ws setup`.'));
+ }
+ const url = entryUrl(entry);
+ if (url) urls.set(url, name);
+ }
+ }
+ return { checks: out, urls: [...urls.keys()], configured };
+}
+
+async function probeServers({ urls, env, origin }) {
+ let bearer = null;
+ try { bearer = await bearerFor(env, { origin }); } catch { bearer = null; }
+ return Promise.all(urls.map(async (url) => {
+ try {
+ const { tools } = await listTools(url, { bearer });
+ return ok(`server:${url}`, `${url} answers tools/list`, `${tools.length} tools`);
+ } catch (err) {
+ const needsLogin = /401|403|unauthor/i.test(err.message);
+ if (needsLogin) return fail(`server:${url}`, `${url} refused the credential`, err.message, 'Run `npx three-ws login`.');
+ return fail(`server:${url}`, `${url} is unreachable`, err.message, 'Check your network and proxy settings; if it persists, see https://three.ws/status.');
+ }
+ }));
+}
+
+async function checkOrigin(origin) {
+ const started = Date.now();
+ try {
+ const res = await request(`${origin}/.well-known/mcp.json`, { timeoutMs: 10_000 });
+ if (!res.ok) return fail('origin', `${origin} answered ${res.status}`, '', 'Try again shortly; if it persists, see https://three.ws/status.');
+ return ok('origin', `${origin} is reachable`, `${Date.now() - started} ms`);
+ } catch (err) {
+ return fail('origin', `${origin} is unreachable`, err.message, 'Check your network, VPN or proxy. Use --origin to test another deployment.');
+ }
+}
+
+export async function runChecks({ env, origin }) {
+ const checks = [checkNode()];
+ const { check, store } = checkStoreFile(env);
+ checks.push(check);
+ const [originCheck, authCheck] = await Promise.all([checkOrigin(origin), checkAuth({ env, origin, store })]);
+ checks.push(originCheck, authCheck);
+ const clients = checkClients({ env, origin });
+ checks.push(...clients.checks);
+ if (!clients.configured) checks.push(warn('clients', 'No client has three.ws configured', '', 'Run `npx three-ws --claude` (or --cursor, --codex, --vscode, --windsurf).'));
+ if (originCheck.status === 'ok' && clients.urls.length) checks.push(...(await probeServers({ urls: clients.urls, env, origin })));
+ return checks;
+}
+
+export async function doctor(ctx) {
+ const checks = await runChecks({ env: ctx.env, origin: ctx.origin });
+ const failed = checks.filter((x) => x.status === 'fail').length;
+ const warned = checks.filter((x) => x.status === 'warn').length;
+ if (ctx.flags.json) {
+ printJson({ ok: failed === 0, failed, warnings: warned, checks });
+ return failed ? 1 : 0;
+ }
+ line(`${c.bold('three-ws doctor')} ${c.dim(ctx.origin)}`);
+ for (const x of checks) {
+ const mark = x.status === 'ok' ? c.green(sym.ok) : x.status === 'warn' ? c.yellow(sym.warn) : c.red(sym.fail);
+ line(` ${mark} ${x.title}${x.detail ? c.dim(` ${x.detail}`) : ''}`);
+ if (x.fix) line(` ${c.cyan(sym.arrow)} ${x.fix}`);
+ }
+ line('');
+ line(failed ? c.red(`${failed} problem(s) found.`) : warned ? c.yellow(`No failures, ${warned} warning(s).`) : c.green('Everything checks out.'));
+ return failed ? 1 : 0;
+}
diff --git a/packages/three-ws-cli/src/commands/live.js b/packages/three-ws-cli/src/commands/live.js
new file mode 100644
index 000000000..13c9e9432
--- /dev/null
+++ b/packages/three-ws-cli/src/commands/live.js
@@ -0,0 +1,134 @@
+// Live state from the terminal. Read-only: nothing here signs or moves funds.
+//
+// three-ws agent status [id|name] each agent's wallet balance, page and body
+// three-ws team [list] your specialist teams
+// three-ws team status <id|name> one team: roster, wallets, findings, last error
+//
+// Backed by GET /api/agents, POST /api/agents/balances (real on-chain valuation,
+// cached 60s server side) and GET /api/teams[/:id].
+
+import { c, line, rows, sym, printJson, shortAddress } from '../ui.js';
+import { bearerFor } from '../oauth.js';
+import { requestJson, ApiError } from '../http.js';
+
+async function authed(ctx) {
+ const bearer = await bearerFor(ctx.env, { origin: ctx.origin });
+ if (!bearer) throw new ApiError('sign in first: `npx three-ws login` (or set THREE_WS_API_KEY)', { code: 'login_required' });
+ return { authorization: `Bearer ${bearer}` };
+}
+
+const ago = (iso) => {
+ if (!iso) return 'never';
+ const secs = Math.max(0, Math.round((Date.now() - new Date(iso).getTime()) / 1000));
+ if (secs < 90) return `${secs}s ago`;
+ if (secs < 5400) return `${Math.round(secs / 60)}m ago`;
+ if (secs < 129600) return `${Math.round(secs / 3600)}h ago`;
+ return `${Math.round(secs / 86400)}d ago`;
+};
+
+const money = (n, digits = 2) => (Number.isFinite(n) ? n.toFixed(digits) : '?');
+
+function pick(list, key, label) {
+ if (!key) return list;
+ const k = key.toLowerCase();
+ const hit = list.filter((x) => x.id === key || x.id.startsWith(key) || String(x.name || '').toLowerCase() === k);
+ if (!hit.length) throw new Error(`no ${label} "${key}" on this account. Run without an argument to list them.`);
+ if (hit.length > 1) throw new Error(`"${key}" matches ${hit.length} ${label}s (${hit.map((h) => h.id.slice(0, 8)).join(', ')}). Use an id.`);
+ return hit;
+}
+
+export async function agentStatus(ctx) {
+ const headers = await authed(ctx);
+ const { agents = [] } = await requestJson(`${ctx.origin}/api/agents`, { headers });
+ const chosen = pick(agents, ctx.positionals[0], 'agent');
+ const ids = chosen.map((a) => a.id);
+ const balances = ids.length
+ ? (await requestJson(`${ctx.origin}/api/agents/balances`, { method: 'POST', headers, json: { ids } })).data || {}
+ : {};
+ const view = chosen.map((a) => {
+ const b = balances[a.id] || {};
+ return {
+ id: a.id,
+ name: a.name,
+ page: `${ctx.origin}/agents/${a.id}`,
+ has_body: Boolean(a.avatar_id),
+ wallet: a.solana_address || null,
+ wallet_ready: a.walletReady ?? null,
+ sol: b.sol ?? null,
+ usdc: b.usdc ?? null,
+ usd: b.usd ?? null,
+ pnl_24h: b.pnl ?? null,
+ };
+ });
+ if (ctx.flags.json) {
+ printJson({ agents: view });
+ return 0;
+ }
+ if (!view.length) {
+ line('No agents on this account yet.');
+ line(c.dim(' Create one: npx three-ws create "Nova"'));
+ return 0;
+ }
+ for (const a of view) {
+ line(`${c.bold(a.name)} ${c.dim(a.id)}`);
+ rows([
+ ['Page', c.cyan(a.page)],
+ ['Body', a.has_body ? 'has a 3D avatar' : c.yellow('none yet; add one on its page')],
+ ['Wallet', a.wallet ? `${shortAddress(a.wallet)} ${a.wallet_ready === false ? c.yellow('(preparing)') : ''}` : c.dim('none')],
+ ['Balance', a.usd == null ? c.dim('not priced yet') : `${money(a.sol, 4)} SOL, ${money(a.usdc)} USDC, about $${money(a.usd)}`],
+ ], ' ');
+ line('');
+ }
+ return 0;
+}
+
+export async function team(ctx) {
+ const [sub, ...rest] = ctx.positionals;
+ const headers = await authed(ctx);
+ const get = (path) => requestJson(`${ctx.origin}${path}`, { headers }).catch((err) => {
+ if (err.status === 404) throw new ApiError(`${ctx.origin} does not serve teams yet. Try without --origin, or update.`, { status: 404 });
+ throw err;
+ });
+ const { data: teams = [] } = await get('/api/teams');
+
+ if (!sub || sub === 'list') {
+ if (ctx.flags.json) {
+ printJson({ teams });
+ return 0;
+ }
+ if (!teams.length) {
+ line('No teams yet.');
+ line(c.dim(` Create one at ${ctx.origin}/teams`));
+ return 0;
+ }
+ for (const t of teams) {
+ line(`${c.bold(t.name)} ${c.dim(t.id)} ${t.status}, ${t.network}, ${t.member_count} members, last finding ${ago(t.last_finding_at)}`);
+ line(` ${c.dim(t.roster.map((r) => `${r.role}: ${r.name}`).join(' '))}`);
+ }
+ return 0;
+ }
+
+ const key = sub === 'status' ? rest[0] : sub;
+ const [match] = pick(teams, key, 'team');
+ if (!match) throw new Error('usage: three-ws team status <id|name>');
+ const { data: t } = await get(`/api/teams/${match.id}`);
+ if (ctx.flags.json) {
+ printJson({ team: t });
+ return 0;
+ }
+ line(`${c.bold(t.name)} ${c.dim(t.id)}`);
+ rows([
+ ['Status', `${t.status} on ${t.network}`],
+ ['Page', c.cyan(`${ctx.origin}${t.page_url}`)],
+ ['Findings', `${t.findings.total} total, ${t.findings.last_24h} in the last 24h, latest ${ago(t.findings.last_at)}`],
+ ...(t.trader_balance_sol != null ? [['Trader wallet', `${money(t.trader_balance_sol, 4)} SOL`]] : []),
+ ...(t.missing_roles.length ? [['Missing', c.yellow(`${t.missing_roles.join(', ')}; repair at ${ctx.origin}${t.page_url}`)]] : []),
+ ...(t.last_error ? [['Last error', c.red(t.last_error)]] : []),
+ ], ' ');
+ line('');
+ for (const m of t.members) {
+ const a = m.agent || {};
+ line(` ${c.green(sym.ok)} ${String(m.role).padEnd(11)} ${a.name || m.agent_id} ${c.dim(a.wallet ? shortAddress(a.wallet) : '')}`);
+ }
+ return 0;
+}
diff --git a/packages/three-ws-cli/src/commands/quick.js b/packages/three-ws-cli/src/commands/quick.js
new file mode 100644
index 000000000..c672b0da7
--- /dev/null
+++ b/packages/three-ws-cli/src/commands/quick.js
@@ -0,0 +1,46 @@
+// `npx three-ws --claude` (and --cursor, --codex, --vscode, --windsurf, --gemini,
+// --bob, --hermes): the whole setup for the named clients, no prompts.
+//
+// It is `setup --clients <ids> --yes` with two guarantees the one-line install
+// path needs: client config files never hold a secret (every entry goes through
+// the local proxy, which reads the owner-only credential store), and Claude Code
+// also gets the three.ws skill so the assistant knows how to use the tools.
+
+import { setup } from './setup.js';
+import { installClaudeSkills } from '../claude-skills.js';
+import { c, line, sym } from '../ui.js';
+
+// flag name -> client id in clients/index.js
+export const CLIENT_FLAGS = {
+ claude: 'claude-code',
+ cursor: 'cursor',
+ codex: 'codex',
+ vscode: 'vscode',
+ windsurf: 'windsurf',
+ gemini: 'gemini',
+ bob: 'bob',
+ hermes: 'hermes',
+};
+
+/** Client ids named by per-client flags, in a stable order. */
+export function clientsFromFlags(flags) {
+ return Object.entries(CLIENT_FLAGS).filter(([flag]) => flags[flag]).map(([, id]) => id);
+}
+
+export async function quick(ctx) {
+ const ids = clientsFromFlags(ctx.flags);
+ ctx.flags.clients = [...new Set([...(ctx.flags.clients ? ctx.flags.clients.split(',') : []), ...ids])].join(',');
+ ctx.flags.yes = true;
+ ctx.flags.proxy = true;
+ ctx.flags.secretless = true;
+ const code = await setup(ctx);
+ if (code !== 0 || !ids.includes('claude-code')) return code;
+
+ const result = await installClaudeSkills({ origin: ctx.origin, env: ctx.env, project: Boolean(ctx.flags.project) });
+ if (!ctx.flags.json) {
+ if (result.error) line(`${c.yellow(sym.warn)} Claude skill not installed: ${result.error}`);
+ else line(`${c.green(sym.ok)} Claude skill ${result.changed ? 'installed' : 'already up to date'}: ${result.file}`);
+ line(c.dim(' Restart Claude Code, then try: claude "launch my agent"'));
+ }
+ return result.error ? 1 : 0;
+}
diff --git a/packages/three-ws-cli/src/commands/setup.js b/packages/three-ws-cli/src/commands/setup.js
index 9aa02d64f..1dcc4479c 100644
--- a/packages/three-ws-cli/src/commands/setup.js
+++ b/packages/three-ws-cli/src/commands/setup.js
@@ -144,7 +144,7 @@ export async function setup(ctx) {
// 6. Write.
const apiKey = mode === 'apikey' ? readStore(env).auth.key : null;
- const writes = applyToClients({ clients, servers, packages, mode, apiKey, stdioKey, liveTools, forceProxy: Boolean(flags.proxy), project: Boolean(flags.project), origin, env });
+ const writes = applyToClients({ clients, servers, packages, mode, apiKey, stdioKey, liveTools, forceProxy: Boolean(flags.proxy), secretless: Boolean(flags.secretless), project: Boolean(flags.project), origin, env });
const selections = readStore(env).tools || {};
const printed = printOnly
? Object.fromEntries(servers.map((s) => [s.slug, buildEntry({ client: PRINT_CLIENT, server: s, mode, apiKey, selection: selections[s.slug], liveTools: liveTools[s.slug], forceProxy: Boolean(flags.proxy) })]))
diff --git a/packages/three-ws-cli/src/configure.js b/packages/three-ws-cli/src/configure.js
index 845ed0edd..9a0f8293f 100644
--- a/packages/three-ws-cli/src/configure.js
+++ b/packages/three-ws-cli/src/configure.js
@@ -52,7 +52,7 @@ export function ensureSelections(servers, { financial = false, env = systemEnv()
* Write each server (and stdio package) into each client. Returns one result
* per client: { client, file, servers: [slug], error }.
*/
-export function applyToClients({ clients, servers, packages = [], mode, apiKey = null, stdioKey = null, liveTools = {}, forceProxy = false, project = false, origin, env = systemEnv() }) {
+export function applyToClients({ clients, servers, packages = [], mode, apiKey = null, stdioKey = null, liveTools = {}, forceProxy = false, secretless = false, project = false, origin, env = systemEnv() }) {
const store = readStore(env);
return clients.map((client) => {
const written = [];
@@ -68,6 +68,7 @@ export function applyToClients({ clients, servers, packages = [], mode, apiKey =
selection: store.tools?.[server.slug] || null,
liveTools: liveTools[server.slug] || null,
forceProxy,
+ secretless,
});
file = writeServer(client, server.slug, entry, env, opts);
written.push(server.slug);
diff --git a/packages/three-ws-cli/src/entries.js b/packages/three-ws-cli/src/entries.js
index 1bd4520a4..03db5fef3 100644
--- a/packages/three-ws-cli/src/entries.js
+++ b/packages/three-ws-cli/src/entries.js
@@ -36,9 +36,9 @@ export function usesProxy({ client, server, mode, forceProxy = false }) {
return server.auth === 'required' && mode !== 'apikey';
}
-export function buildEntry({ client, server, mode, apiKey = null, selection = null, liveTools = null, forceProxy = false, proxy = proxyInvocation() }) {
+export function buildEntry({ client, server, mode, apiKey = null, selection = null, liveTools = null, forceProxy = false, secretless = false, proxy = proxyInvocation() }) {
const needsAuth = server.auth === 'required';
- if (needsAuth && mode === 'apikey' && !apiKey) throw new Error(`an API key is required to configure ${server.slug}`);
+ if (needsAuth && mode === 'apikey' && !apiKey && !secretless) throw new Error(`an API key is required to configure ${server.slug}`);
if (!usesProxy({ client, server, mode, forceProxy })) {
const headers = {};
@@ -52,7 +52,9 @@ export function buildEntry({ client, server, mode, apiKey = null, selection = nu
}
const env = {};
- if (needsAuth && mode === 'apikey') env.THREE_WS_API_KEY = apiKey;
+ // secretless: the proxy reads the key from the owner-only credential store,
+ // so the client's config file never holds it.
+ if (needsAuth && mode === 'apikey' && !secretless) env.THREE_WS_API_KEY = apiKey;
return client.stdio({
command: proxy.command,
args: [...proxy.args, 'proxy', server.url, '--server', server.slug],