The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(cli): add agent local-cli command for skill install and env export
Dotta654463c28f0d
diff --git a/cli/src/commands/client/agent.ts b/cli/src/commands/client/agent.tsindex 2a1b4243d9..c98ca15884 100644--- a/cli/src/commands/client/agent.ts+++ b/cli/src/commands/client/agent.ts@@ -1,5 +1,9 @@import { Command } from "commander";import type { Agent } from "@paperclipai/shared";+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { fileURLToPath } from "node:url";import {addCommonClientOptions,formatInlineRecord,@@ -13,6 +17,107 @@ interface AgentListOptions extends BaseClientOptions {companyId?: string;}+interface AgentLocalCliOptions extends BaseClientOptions {+ companyId?: string;+ keyName?: string;+ installSkills?: boolean;+}++interface CreatedAgentKey {+ id: string;+ name: string;+ token: string;+ createdAt: string;+}++interface SkillsInstallSummary {+ tool: "codex" | "claude";+ target: string;+ linked: string[];+ skipped: string[];+ failed: Array<{ name: string; error: string }>;+}++const __moduleDir = path.dirname(fileURLToPath(import.meta.url));+const PAPERCLIP_SKILLS_CANDIDATES = [+ path.resolve(__moduleDir, "../../../../../skills"), // dev: cli/src/commands/client -> repo root/skills+ path.resolve(process.cwd(), "skills"),+];++function codexSkillsHome(): string {+ const fromEnv = process.env.CODEX_HOME?.trim();+ const base = fromEnv && fromEnv.length > 0 ? fromEnv : path.join(os.homedir(), ".codex");+ return path.join(base, "skills");+}++function claudeSkillsHome(): string {+ const fromEnv = process.env.CLAUDE_HOME?.trim();+ const base = fromEnv && fromEnv.length > 0 ? fromEnv : path.join(os.homedir(), ".claude");+ return path.join(base, "skills");+}++async function resolvePaperclipSkillsDir(): Promise<string | null> {+ for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {+ const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);+ if (isDir) return candidate;+ }+ return null;+}++async function installSkillsForTarget(+ sourceSkillsDir: string,+ targetSkillsDir: string,+ tool: "codex" | "claude",+): Promise<SkillsInstallSummary> {+ const summary: SkillsInstallSummary = {+ tool,+ target: targetSkillsDir,+ linked: [],+ skipped: [],+ failed: [],+ };++ await fs.mkdir(targetSkillsDir, { recursive: true });+ const entries = await fs.readdir(sourceSkillsDir, { withFileTypes: true });+ for (const entry of entries) {+ if (!entry.isDirectory()) continue;+ const source = path.join(sourceSkillsDir, entry.name);+ const target = path.join(targetSkillsDir, entry.name);+ const existing = await fs.lstat(target).catch(() => null);+ if (existing) {+ summary.skipped.push(entry.name);+ continue;+ }++ try {+ await fs.symlink(source, target);+ summary.linked.push(entry.name);+ } catch (err) {+ summary.failed.push({+ name: entry.name,+ error: err instanceof Error ? err.message : String(err),+ });+ }+ }++ return summary;+}++function buildAgentEnvExports(input: {+ apiBase: string;+ companyId: string;+ agentId: string;+ apiKey: string;+}): string {+ const escaped = (value: string) => value.replace(/'/g, "'\"'\"'");+ return [+ `export PAPERCLIP_API_URL='${escaped(input.apiBase)}'`,+ `export PAPERCLIP_COMPANY_ID='${escaped(input.companyId)}'`,+ `export PAPERCLIP_AGENT_ID='${escaped(input.agentId)}'`,+ `export PAPERCLIP_API_KEY='${escaped(input.apiKey)}'`,+ ].join("\n");+}+export function registerAgentCommands(program: Command): void {const agent = program.command("agent").description("Agent operations");@@ -71,4 +176,96 @@ export function registerAgentCommands(program: Command): void {}}),);++ addCommonClientOptions(+ agent+ .command("local-cli")+ .description(+ "Create an agent API key, install local Paperclip skills for Codex/Claude, and print shell exports",+ )+ .argument("<agentRef>", "Agent ID or shortname/url-key")+ .requiredOption("-C, --company-id <id>", "Company ID")+ .option("--key-name <name>", "API key label", "local-cli")+ .option(+ "--no-install-skills",+ "Skip installing Paperclip skills into ~/.codex/skills and ~/.claude/skills",+ )+ .action(async (agentRef: string, opts: AgentLocalCliOptions) => {+ try {+ const ctx = resolveCommandContext(opts, { requireCompany: true });+ const query = new URLSearchParams({ companyId: ctx.companyId ?? "" });+ const agentRow = await ctx.api.get<Agent>(+ `/api/agents/${encodeURIComponent(agentRef)}?${query.toString()}`,+ );++ const now = new Date().toISOString().replaceAll(":", "-");+ const keyName = opts.keyName?.trim() ? opts.keyName.trim() : `local-cli-${now}`;+ const key = await ctx.api.post<CreatedAgentKey>(`/api/agents/${agentRow.id}/keys`, { name: keyName });++ const installSummaries: SkillsInstallSummary[] = [];+ if (opts.installSkills !== false) {+ const skillsDir = await resolvePaperclipSkillsDir();+ if (!skillsDir) {+ throw new Error(+ "Could not locate local Paperclip skills directory. Expected ./skills in the repo checkout.",+ );+ }++ installSummaries.push(+ await installSkillsForTarget(skillsDir, codexSkillsHome(), "codex"),+ await installSkillsForTarget(skillsDir, claudeSkillsHome(), "claude"),+ );+ }++ const exportsText = buildAgentEnvExports({+ apiBase: ctx.api.apiBase,+ companyId: agentRow.companyId,+ agentId: agentRow.id,+ apiKey: key.token,+ });++ if (ctx.json) {+ printOutput(+ {+ agent: {+ id: agentRow.id,+ name: agentRow.name,+ urlKey: agentRow.urlKey,+ companyId: agentRow.companyId,+ },+ key: {+ id: key.id,+ name: key.name,+ createdAt: key.createdAt,+ token: key.token,+ },+ skills: installSummaries,+ exports: exportsText,+ },+ { json: true },+ );+ return;+ }++ console.log(`Agent: ${agentRow.name} (${agentRow.id})`);+ console.log(`API key created: ${key.name} (${key.id})`);+ if (installSummaries.length > 0) {+ for (const summary of installSummaries) {+ console.log(+ `${summary.tool}: linked=${summary.linked.length} skipped=${summary.skipped.length} failed=${summary.failed.length} target=${summary.target}`,+ );+ for (const failed of summary.failed) {+ console.log(` failed ${failed.name}: ${failed.error}`);+ }+ }+ }+ console.log("");+ console.log("# Run this in your shell before launching codex/claude:");+ console.log(exportsText);+ } catch (err) {+ handleCommandError(err);+ }+ }),+ { includeCompany: false },+ );}diff --git a/doc/CLI.md b/doc/CLI.mdindex b56abf75b8..6f945656d4 100644--- a/doc/CLI.md+++ b/doc/CLI.md@@ -116,6 +116,20 @@ pnpm paperclipai issue release <issue-id>```shpnpm paperclipai agent list --company-id <company-id>pnpm paperclipai agent get <agent-id>+pnpm paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>+```++`agent local-cli` is the quickest way to run local Claude/Codex manually as a Paperclip agent:++- creates a new long-lived agent API key+- installs missing Paperclip skills into `~/.codex/skills` and `~/.claude/skills`+- prints `export ...` lines for `PAPERCLIP_API_URL`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_AGENT_ID`, and `PAPERCLIP_API_KEY`++Example for shortname-based local setup:++```sh+pnpm paperclipai agent local-cli codexcoder --company-id <company-id>+pnpm paperclipai agent local-cli claudecoder --company-id <company-id>```## Approval Commandsdiff --git a/docs/adapters/claude-local.md b/docs/adapters/claude-local.mdindex 254689a280..3b80f288f0 100644--- a/docs/adapters/claude-local.md+++ b/docs/adapters/claude-local.md@@ -47,6 +47,14 @@ If resume fails with an unknown session error, the adapter automatically retriesThe adapter creates a temporary directory with symlinks to Paperclip skills and passes it via `--add-dir`. This makes skills discoverable without polluting the agent's working directory.+For manual local CLI usage outside heartbeat runs (for example running as `claudecoder` directly), use:++```sh+pnpm paperclipai agent local-cli claudecoder --company-id <company-id>+```++This installs Paperclip skills in `~/.claude/skills`, creates an agent API key, and prints shell exports to run as that agent.+## Environment TestUse the "Test Environment" button in the UI to validate the adapter config. It checks:diff --git a/docs/adapters/codex-local.md b/docs/adapters/codex-local.mdindex d87172f8c5..60725a49d9 100644--- a/docs/adapters/codex-local.md+++ b/docs/adapters/codex-local.md@@ -30,6 +30,14 @@ Codex uses `previous_response_id` for session continuity. The adapter serializesThe adapter symlinks Paperclip skills into the global Codex skills directory (`~/.codex/skills`). Existing user skills are not overwritten.+For manual local CLI usage outside heartbeat runs (for example running as `codexcoder` directly), use:++```sh+pnpm paperclipai agent local-cli codexcoder --company-id <company-id>+```++This installs any missing skills, creates an agent API key, and prints shell exports to run as that agent.+## Environment TestThe environment test checks: