# AgentLed CLI — Install & Connect

One command takes you from zero to a connected workspace with MCP wired into your AI editor.

\`\`\`bash
npx @agentled/cli setup
\`\`\`

## What \`agentled setup\` does

1. **Version check.** Warns if the CLI is outdated and tells you how to update.
2. **Browser sign-in + workspace selection.** Opens a browser; you sign in (or sign up) and pick a workspace. The CLI mints a workspace API key and stores a profile in \`~/.agentled/config.json\`.
3. **Workspace folder scaffold.** Creates \`agentled_<workspace-slug>/\` in the current directory — logs pulled, dryruns, decisions, workflow drafts, knowledge-graph drafts, executions debug bundles. One folder per workspace; multiple workspaces never share a folder.
4. **MCP auto-config.** Detects your AI editor (Claude Code, Codex, Cursor, Claude Desktop, Windsurf) and writes the AgentLed MCP server into its config.
5. **Skill install.** Routes to the right target by client:
    - Claude Code / Claude Desktop → \`~/.claude/skills/agentled/\`
    - Codex → \`~/.codex/instructions/agentled/\`
    - Cursor / Windsurf → skipped with a hint (no native Claude-format skill surface)

   The skill encodes the dry-run protocol, incremental authoring rules, valid step types, and credit-efficient testing guidance — without it, the agent has the tools but loses the playbook.
6. **Knowledge probe.** Reads \`knowledge.company.profile\` from the workspace. If missing, prompts for company name / website / use case and writes the long-form profile back to the same key via \`upsert_knowledge_text\`. The probe reads what the prompt writes, so this step does not re-fire on subsequent runs. If present, prints a one-line summary.
7. **Restart prompt.** Tells you to restart your MCP client so the new connection is picked up (Claude Code: \`/mcp\` reconnect or new session; Codex/Cursor: reopen the app). Without the restart, MCP tools won't see the new workspace.

Global docs and example workflows live in \`~/.agentled/\` (a small README + pointer to the public best-practices repo; examples are pulled on demand so you stay in sync with the canonical repo). The full public best-practices repo is at https://github.com/Agentled/agentic-ops.

## Requirements
- Node.js 18+
- An MCP-compatible client (Claude Code, Codex, Cursor, Claude Desktop, Windsurf, …) — optional but recommended.

## Components (à-la-carte)

Skip the orchestrated flow and run pieces individually:

\`\`\`bash
npm install -g @agentled/cli
agentled auth login            # browser auth + workspace selection + skill install
agentled init                   # scaffold agentled_<slug>/
\`\`\`

Verify with \`agentled --version\` and \`agentled auth status\`. Re-install or update the skill manually with \`agentled skills install\` (or \`agentled skills update\` to bump to the bundled version).

## Headless / API-key path (no browser)

For AI agents without browser access, CI runners, or remote shells, generate a key at https://www.agentled.app → Workspace Settings → Developer (key starts with \`wsk_\`):

\`\`\`bash
agentled auth login --key wsk_...
agentled init
\`\`\`

Or register the MCP server directly with your client:

\`\`\`bash
claude mcp add agentled-<workspace-name> \\
  -e AGENTLED_API_KEY=wsk_... \\
  -- npx -y @agentled/mcp-server
\`\`\`

For Codex / Cursor / other MCP clients, register an MCP server with:
- command: \`npx\`
- args: \`["-y", "@agentled/mcp-server"]\`
- env: \`{ "AGENTLED_API_KEY": "wsk_..." }\`

## Folder layout after setup

After \`agentled setup\` you will see two folders:

\`\`\`
~/.agentled/                 # global, shared across workspaces
  config.json                # saved workspace profiles
  README.md                  # pointer to https://github.com/Agentled/agentic-ops
  examples/                  # populated on demand from agentic-ops

agentled_<workspace-slug>/   # one per workspace, in cwd
  README.md
  worklog.md                 # rolling session log
  decisions/                 # YYYY-MM-DD-<slug>.md
  workflows/                 # local pipeline JSON drafts
  groups/                    # WorkflowGroup / kit specs
  kg/                        # local mirrors of KG list schemas / text drafts
  executions/                # debug bundles for failed runs
  drafts/                    # scratch space
\`\`\`

Local folder = agent scratch (drafts, deliberation, raw debug). Workspace KG = team truth (durable, queryable, shared). Don't conflate them.

**Sync rule:** at the end of any meaningful working session — and explicitly on "save" / "wrap up" — summarize durable outcomes (final decisions, current themes, active sources, workflow purpose statements) and write them to the workspace KG via \`upsert_knowledge_text\` (narrative) or \`upsert_knowledge_rows\` (structured). Use stable keys like \`decisions.current-theme\`, \`groups.<slug>.spec\`, \`workflows.<id>.purpose\`. Append a one-line entry to \`worklog.md\`. Don't sync raw debug bundles, full timelines, or abandoned drafts.

**On session start:** if \`agentled_<workspace-slug>/\` for the active workspace exists, read its README + recent decisions + worklog before proposing anything. With multiple workspaces, only act on the folder matching the currently active workspace from \`agentled auth current\` — never operate on a sibling.

## Agent instructions

If you are an AI coding agent helping a user connect:

1. Run \`npx @agentled/cli setup\` yourself via your shell tool. Bash runs on the user's machine, so the browser opens on the user's machine. Do not tell the user to run it manually.
2. If the command blocks waiting for the OAuth callback, run it in the background and surface the printed auth URL so the user can click it.
3. After it completes, tell the user explicitly: "Restart your MCP client to pick up this workspace." Don't wait for them to notice MCP tools aren't visible.
4. If the user already has a \`wsk_\` key, use \`agentled auth login --key wsk_...\` instead — never invent or guess a key.
5. Read the scaffolded \`agentled_<workspace-slug>/README.md\` for the conventions before doing further work. Read the installed skill for the dry-run protocol, incremental authoring rules, and credit-efficient testing patterns.

## Links
- npm: https://www.npmjs.com/package/@agentled/cli
- MCP server npm: https://www.npmjs.com/package/@agentled/mcp-server
- Source: https://github.com/agentled/mcp-server
- Best-practice patterns: https://github.com/Agentled/agentic-ops
- MCP setup: https://www.agentled.ai/docs/mcp.md