# @agentled/cli Command-line access to Agentled workflows, apps, knowledge, and workspace operations. This is the canonical customer-facing CLI package for Agentled. It uses the same external API surface as the MCP server, but without MCP tool-definition overhead in the agent context window. ## Install ```bash npm install -g @agentled/cli ``` ## Quick Start ```bash npx -y @agentled/cli setup agentled auth current agentled workflows list agentled workspace info agentled workspace company-profile ``` ### Use-case operating guides For existing workflow work, map the workflow to its business use case and read the linked operating guide before editing or running backfills: ```bash agentled workflows get --format json agentled use-cases get --format json agentled knowledge text --format json ``` `workflows get` includes `useCaseContext` when a use case is linked. `use-cases get` includes `operatingGuides`, read commands, linked workflow refs, KG refs, data-source refs, and missing-guide warnings. ### First-run setup for AI agents `agentled setup` signs in through the browser, stores the selected workspace in `~/.agentled/config.json`, registers the MCP server, installs the matching Agentled skill, and probes workspace knowledge. When the target AI agent is known, pass it explicitly instead of relying on environment auto-detection: ```bash # Codex npx -y @agentled/cli setup --mcp-client codex # Claude Code npx -y @agentled/cli setup --mcp-client claude-code # Cursor / Windsurf / Claude Desktop npx -y @agentled/cli setup --mcp-client cursor npx -y @agentled/cli setup --mcp-client windsurf npx -y @agentled/cli setup --mcp-client claude-desktop ``` OpenClaw currently has skill installation support but not MCP auto-config support in `agentled setup`. Authenticate once and install its matching skill bundle: ```bash npx -y @agentled/cli@0.8.2 auth login npx -y @agentled/cli skills install --target openclaw ``` Use `--reauth` when switching workspaces or recovering from a failed browser login: ```bash npx -y @agentled/cli setup --reauth --mcp-client codex ``` After setup, restart or reconnect the AI agent so it starts a fresh MCP server process with the new credentials. ### Portable Agent Plugin v1 for Hermes The MCP package also ships the standards-based portable wrapper at `agentled-mcp-server/plugins/agentled/`. It reuses the existing Social Media Management Markdown skill and declares a pinned local stdio MCP server without embedding credentials or workspace state. See the wrapper's [`README.md`](../../agentled-mcp-server/plugins/agentled/README.md) for the Hermes v0.20.2 install, explicit enablement, local-profile authentication, reload, status, and removal steps. The stable Hermes installer accepts a Git URL or `owner/repo[/subdir]`; it does not accept the old local-directory command. The public install command below is future/post-publication guidance only, not a claim of current publication or observed installation. Prefer its immutable `--ref` form: ```bash # Future, after publication; not a current availability claim. hermes plugins install Agentled/mcp-server/plugins/agentled \ --ref <40-character-commit-sha> --no-enable hermes plugins list hermes plugins enable agentled ``` After a controlled install, start a fresh Hermes session or use `/reload-mcp`. Use only bounded read-only MCP tool discovery and status inspection for proof; this bounded check does not make the enabled server read-only. Authenticate the local profile with the existing CLI flow, then reload Hermes: ```bash npx -y @agentled/cli@0.8.2 auth login npx -y @agentled/cli@0.8.2 auth status npx -y @agentled/cli@0.8.2 auth use # only when switching profiles ``` The pinned stdio server reads the active `~/.agentled/config.json`. Newly created config files use mode `0600`; pre-existing config files are not automatically tightened. Hermes running as the same OS user can read and use the mode-0600 credential. Stdio/API-key calls are not narrowed by hosted OAuth `mcp:read` today. Do not also register the native remote AgentLed MCP, which would duplicate AgentLed servers and tools. This is trusted-local-agent access for an owner/admin machine, not read-only or least privilege. When an active CLI profile exists, enabling or reloading exposes to Hermes the broad AgentLed workspace read/write MCP surface authorized by that workspace API key. Installation without an active credential grants no AgentLed authority; authenticated enablement does. Enabling executes the pinned npm package locally as the current user, requiring Node.js `>=18`, `npx`, and first-run npm registry access. Provider calls, spending, approval-gated publish/send actions, and routines still follow AgentLed's separate runtime policies. The portable package contains no key or provider credential. Codex plugin exports include Agentled lifecycle hooks for in-session guidance and final-handoff nudges. Hooks do not store feedback, create reminders, call Agentled APIs, spend credits, or write workspace data. After installing or updating the plugin, run `/hooks` inside Codex to review and trust those local hook definitions. Use Codex automations for outside-workspace FDE cadence such as Outlook/client email follow-up, vendor replies, repo/build checks, and weekly operator reviews. Use Agentled routines for Agentled workspace/runtime checks such as workflow health, execution review, workspace summaries, and managed-agent operations. ## Authentication and workspace profiles The CLI stores multiple saved workspace profiles in `~/.agentled/config.json`. Normal commands use the active saved workspace by default. ```bash # Add or refresh a workspace profile agentled auth login # Inspect the active workspace profile agentled auth current # List all saved workspaces agentled auth list # Switch the active workspace agentled auth use bestseo4u # Target a different saved workspace for one command only agentled --workspace inovexus workflows list # or AGENTLED_WORKSPACE=inovexus agentled workflows list # Remove one saved workspace profile agentled auth remove bestseo4u ``` ### Claude Code skill auto-install (v0.2+) On first successful login, `agentled auth login` installs the bundled Agentled skill into `~/.claude/skills/agentled/` so Claude Code picks up pipeline shape hints (valid step types, common invalid patterns) automatically. Returning users see a line showing the installed version and whether a newer one is available. Skip the auto-install with `--skip-skills`: ```bash agentled auth login --skip-skills ``` Manage the skill manually with the `agentled skills` subcommands: ```bash # Fresh install to ~/.claude/skills/ (or --project for the current project) agentled skills install # Update to the version bundled with this CLI release agentled skills update # Show bundled vs installed versions agentled skills status # Overwrite hand-edited skills (advanced) agentled skills install --force # Install for another agent # Skill-directory agents get the full bundle (router + references/): agentled skills install --target codex # ~/.codex/skills/agentled/ agentled skills install --target openclaw # ~/.openclaw/skills/agentled/ agentled skills install --target hermes # ~/.hermes/skills/automation/agentled/ # Single-file agents get the router + all references flattened into one file: agentled skills install --target cursor # .cursor/rules/agentled.mdc agentled skills install --target agents # AGENTS.md (non-destructive — sidecar if one exists) agentled skills install --target gemini # GEMINI.md # Codex plugin package (manifest + skill bundle) you install via Codex's plugin flow: agentled skills install --target codex-plugin # ./agentled-codex-plugin/ # List the composable reference modules the skill router loads on demand agentled skills list ``` The Codex plugin scaffold includes the Agentled skill plus lifecycle hooks that guide the current Codex session around the Agentled business-loop split: Codex for technical/FDE work, Agentled MCP/CLI for workspace inspection and updates, Codex automations for outside-workspace cadence, and Agentled routines for workspace/runtime checks. The skill is a thin `SKILL.md` router plus on-demand `references/` modules (progressive disclosure — cheap to keep in context). Non-Claude targets get the router and every reference concatenated into one file. ### Runtime skills on AgentEntities AgentEntities can enable runtime skills such as `outcome-solver`, `workflow-manager`, and `agent-manager`. These skills are used consistently by internal chat, channels, routines, CLI, and MCP calls; they are separate from the markdown skill installed into Codex or Claude Code. ```bash # Create an agent with outcome and workflow skills enabled agentled agents create --name "Ops Agent" --skill-ids outcome-solver,workflow-manager # Update an existing agent; empty string disables inherited skills agentled agents update agent-id --skill-ids outcome-solver,workflow-manager agentled agents update agent-id --skill-ids "" # Update agent fields and runtime skills together through one JSON payload agentled agents update agent-id --input '{"name":"Ops Agent","enabledSkills":["outcome-solver","workflow-manager"]}' ``` For `agents update`, choose one update mode: JSON via `--input`/`--file`, or a skill-only update via `--skill-ids`/`--enabled-skills`. Mixing the modes is rejected with an error instead of silently ignoring skill flags. Include `enabledSkills` in the JSON payload when changing agent fields and skills together. ### Reflection AgentFiles Agent reflection context lives in linked markdown AgentFiles, not hidden runtime state. `JOURNAL.md`, `OBJECTIVES.md`, and `PEOPLE.md` are auto-seeded for active chat-only reflection agents and follow the OpenClaw/Hermes-style memory-file pattern: readable, concise, and edited through the same UI/MCP/CLI surfaces. Agents decide what durable signal belongs there; do not store raw transcript logs or update the files for every turn. ```bash agentled agents files list agent-id agentled agents files get agent-id file-id agentled agents files upload agent-id --name JOURNAL.md --file JOURNAL.md --mime-type markdown agentled agents files update agent-id file-id --file JOURNAL.md --mime-type markdown agentled agents files delete agent-id file-id ``` See `docs/AGENT_REFLECTION_FILES.md` for file roles and the manual reflection-routine validation path. ## Auto-validation on create / update `agentled workflows create` and `agentled workflows update` call `validate_workflow` immediately after the API returns 201/200. If validation finds errors, the command: - prints a structured error report (stepId, message, code, suggested fix) - exits with status code **`2`** (distinct from `1` = CLI/network error) - tells you how to re-check, fix, or delete the broken workflow Pass `--skip-validate` to restore the legacy raw-create behavior (useful for CI pipelines that run their own validation logic). ```bash # Create + validate (default) agentled workflows create --file pipeline.json # Create without validation agentled workflows create --file pipeline.json --skip-validate # Safe edit loop for config updates agentled workflows pull --output workflow.json agentled workflows diff --file workflow.json agentled workflows replace --file workflow.json ``` `workflows update --file` and `workflows replace --file` refuse config changes when the file does not carry the remote `metadata.revision` or `updatedAt` token from `workflows pull`, or when the remote workflow changed since that pull. This protects agents from overwriting user edits with an old local working copy. Use `--force` only for intentional overwrites. Use `update` for partial patches. Use `replace` when your pulled local file is the working version and you want remote config fields, including `context`, to match that file. When an update edits a live workflow draft, auto-validation validates the draft config and reports `source: "draft"` in JSON output. You can validate explicitly with `agentled workflows validate --draft` or `--live`. ## Two-phase workflow deletion Workflow deletion requires an explicit server-issued confirmation token. The first command returns a deletion preview and `confirmToken` without deleting anything. Pass that token to the second command to confirm the permanent deletion: ```bash agentled workflows delete agentled workflows delete --confirm-token ``` ## Schema and best-practice patterns (v0.3+) Before writing pipeline JSON, look up the canonical field schema and the matching agentic-ops pattern. These commands avoid the "agent invents step types" failure mode that produces 201-but-broken workflows. ```bash # Full canonical PipelineStep field schema agentled schema # Fields applicable to an aiAction step agentled schema --step-type aiAction # Human-readable instead of JSON agentled schema --format table # List the bundled workflow patterns agentled examples # Print one pattern (by slug, number, or keyword) agentled examples trigger-design agentled examples 04 # loops agentled examples dedup agentled examples 13-entity-pipeline-lifecycle # Summary + link to the canonical public repo agentled best-practices ``` The patterns are maintained publicly at [github.com/agentled/agentic-ops](https://github.com/agentled/agentic-ops). The CLI ships a byte-identical mirror for offline reading; a CI drift test in this repo keeps them in sync. ## Scaffolds and preflight (v0.4+) `agentled workflows scaffold` and `agentled workflows validate --file` let you start from a known-good template and check your draft locally before any API call. Both avoid the "201 Created but silently broken" failure mode. ```bash # List the bundled scaffolds agentled workflows scaffold --list # Print a scaffold to stdout agentled workflows scaffold lead-scoring-kg # Build the common sourcing-to-outreach lifecycle from known-good starters agentled workflows scaffold source-from-platform --out 01-source.json agentled workflows scaffold lead-scoring-kg --out 02-score-qualify.json agentled workflows scaffold list-match-email --out 04-outreach.json agentled workflows scaffold funnel-orchestrator --out 99-orchestrator.json # Mark contacted only after send/queue succeeds; add event/polling workflows # for replies, bounces, opens, and clicks when the channel supports them. # For outreach, add business metrics for contacted prospects, positive replies, # and PCPL. Literal PCPL is a ratio metric with ratioMode:"raw": # prospects_contacted / positive_replies. Reply rate uses the default percent ratio. # Write a scaffold to a file to start editing from agentled workflows scaffold list-match-email --out pipeline.json # Client-side preflight: no API call, catches invalid step types, stripped # root fields (prompt / responseStructure / listKey / appId), dangling # next.stepId, missing required sub-object fields, duplicate step IDs. # Exits 2 on error so CI can gate on it. agentled workflows validate --file pipeline.json # Server-side validate of a stored workflow (unchanged) agentled workflows validate ``` Scaffolds are **pattern shapes, not domain templates** — domain-agnostic placeholders (`candidate`, `metric_a`, `entity_id`) so they adapt to any vertical. See `packages/cli/scaffolds/README.md` for the contract and how to add a new one. | Name | Patterns | Shape | |------|----------|-------| | `minimal` | — | trigger → milestone | | `email-polling-dedup` | 02 + 13 | schedule → fetch emails (label dedup) → loop process → add label | | `source-from-platform` | 13 | schedule → source app → normalize → kg.upsert-rows(status:new) | | `lead-scoring-kg` | 04 + 09 | trigger → kg.read-list → AI scoring loop → knowledgeSync | | `list-match-email` | 08 | trigger → kg.read-list → AI match → composed email (approval gate) → knowledgeSync | | `funnel-orchestrator` | 05 + 13 | schedule → read KG statuses → call child workflows → digest | | `extract-threshold-alert` | 06 + 09 | trigger → AI extract → threshold check → external update → conditional Slack alert → knowledgeSync | Each bundled scaffold passes `workflows validate --file` out of the box. ### Bring your own scaffolds Drop JSON files in `~/.agentled/scaffolds/` or set `AGENTLED_SCAFFOLDS_DIR` to point at a directory. Local scaffolds appear with a `[local]` tag in `scaffold --list`, and local slugs **shadow** bundled ones with the same name — a team can override `list-match-email.json` without waiting on a CLI release. ## Company profile commands ```bash # Get company profile + company knowledge text agentled workspace company-profile # Update top-level company fields agentled workspace update-company-profile --input '{"name":"Acme","urls":["https://acme.com"]}' # Pin an output page to workspace home/sidebar agentled workspace set-output-pin wfl_abc123 weekly-report --label "Weekly Investor Report" --icon-name FileText # List or unpin workspace output shortcuts agentled workspace pinned-outputs agentled workspace set-output-pin wfl_abc123 weekly-report --unpin # Create or inspect saved workspace views agentled workspace-views create --file workspace-view.json agentled workspace-views create --name "Qualified Leads Review" --nav-label Leads --placement '{"type":"use_case","useCaseId":"deal-sourcing@acme"}' --data-sources '[...]' --layout '{...}' agentled views list --status active agentled views get followup-queue agentled views archive followup-queue ``` Workspace views are saved operating-surface manifests over KG, workflows, approvals, agents, routines, action queues, output pages, external APIs, and custom sources. Creating or updating a view does not run workflows, mutate KG rows, send messages, make approval decisions, or spend credits. See `docs/WORKSPACE_VIEWS.md`. Use `name` for the full page title, `navLabel` for short sidebar copy, and `placement` to attach a pinned view to a use case or workflow group. ## DFE client dossiers Local workspace folders created by `agentled init` include `clients/` for offline, local-first client engagement records. Use this for the DFE operating trail: POCs, account context, meeting notes, feedback, decisions, draft replies, and validation evidence. ```bash agentled init inovexus cd agentled_inovexus # Create clients/inovexus/ with structured JSON and Markdown templates agentled clients init inovexus --name "Inovexus" # Capture meeting notes and generate an agent-ready context packet agentled clients meeting new inovexus --title "Weekly workflow review" agentled clients brief inovexus ``` The client dossier commands work from local files and do not change the existing workflow pull/push, fixture, or `agentled test` loop. ## MCP parity command groups (MCP-040) The CLI now includes dedicated command groups matching MCP domains: - `agentled kg create-list|update-list-schema|delete-list|upsert-rows|delete-rows|upsert-text|delete-text` - `agentled agents ...` - `agentled branding get|update` - `agentled memory store|recall|search|list|delete` - `agentled feedback submit ...` - `agentled intent do ...` - `agentled proactive-agents ...` - `agentled workspace-views list|create|get|update|archive` (alias: `agentled views ...`) - `agentled models list` - `agentled clients feedback add|reply|validate` ## Credit Usage and Cost Drivers The CLI does not yet ship first-class credit-reporting commands. Until those land, agents should use the product UI, MCP tools, or external API: - UI: `https://www.agentled.app/en/{workspace}/account/billing/credits-usage` shows the workspace credit breakdown and cost drivers. - MCP: `get_workspace_credits`, `get_workspace_credit_cost_drivers`, and `get_workflow_credits`. - API: `GET /api/external/workspace/credits?period=rolling-30-days&include=costDrivers` and `GET /api/external/workflows/{workflowId}/credits?period=rolling-30-days&include=costDrivers`. Always include the returned `period.label` / `period.display` when reporting a credit total. ## Running workflows Start a workflow execution by id: ```bash # Honors the workflow's configured per-step mocks (default — mocked steps consume zero credits) agentled wf start --input '{"startupUrl":"https://acme.com"}' # Force a real run that ignores all step mocks (consumes real credits) agentled wf start --input '{"startupUrl":"https://acme.com"}' --no-mocks # Explicitly opt in to mocks (same as default, useful in scripts) agentled wf start --input '{...}' --use-mocks ``` Under the hood, `--no-mocks` sets `metadata.mockConfig.disabled = true`, which the orchestrator reads to bypass `step.mock.enabledByDefault` for every step. You can also pass that directly via `--metadata '{"mockConfig":{"disabled":true}}'` if you need to combine it with other metadata fields. `agentled wf start` always returns `executionInputId`, which identifies the submitted input/run record. It may also return `executionId` when the async execution row has already been created. Commands such as `agentled executions get` require the real `executionId`. If start only returns `executionInputId`, run `agentled executions list --limit 5` and find the row whose `pipelineExecutionInputId` matches; use that row's `id` as the execution ID. ### Monitor workflows started from CLI chat The browser chat automatically runs `monitorWorkflowExecution` and continues the conversation when a workflow reaches a terminal state. The CLI has no browser continuation loop, so a completed `chat-result` can legitimately say `Run started` while the linked workflow is still running. That is a handoff, not the final user outcome. When `agentled chat` or `agentled chat-result` returns a `workflowId`, `executionId`, run URL, or wording that a workflow started: 1. Do not resend the original chat prompt. 2. Resolve the execution ID if only an input ID was returned. 3. Poll the execution until it reaches a terminal state. 4. Read the relevant step outputs and continue the same chat session with the verified result or explicit no-match/failure outcome. ```bash # First finish the durable assistant turn. agentled chat-result --format json # Find the execution if the turn only identifies the workflow or input row. agentled executions list --limit 5 --direction desc --format json # Poll this command until status is completed, failed, stopped, or canceled. agentled executions get --format json # Inspect the result-producing step instead of trusting the initial handoff text. agentled executions step-output --format json # Deliver the terminal outcome through the same conversation. agentled chat --session-id \ "The workflow is terminal. Report its verified result to the user; do not restart it." \ --format json ``` For an agent operating the CLI, starting a workflow is not task completion. Completion means the execution is terminal and the result has been reported to the user. Treat `stopped` as terminal too: it often represents an intentional no-results or entry-condition stop rather than a runtime failure. ### Admin execution patch commands The CLI exposes the same exception-only admin patch surface as MCP. These commands require an API key with the `admin:patch` scope and an `--expected-updated-at` value from a fresh execution or timeline read. ```bash # Preview a pending timeline patch without writing or auditing agentled executions patch-timeline-fields \ --reason "Fix malformed pending email subject" \ --expected-updated-at "2026-05-05T10:00:00.000Z" \ --patches '[{"op":"replace","path":"eventContent.email.subject","value":"Updated subject"}]' \ --dry-run # Relabel a terminal timeline row after confirming the outcome agentled executions patch-timeline-fields \ --reason "Relabel timeline after send confirmation" \ --expected-updated-at "2026-05-05T10:00:00.000Z" \ --patches '[{"op":"replace","path":"eventSummary","value":"Anjani Ladia - Email Sent"}]' # Patch execution metadata, for example to relabel a completed outreach run agentled executions patch-execution-fields \ --reason "Relabel completed outreach execution after send confirmation" \ --expected-updated-at "2026-05-05T10:00:00.000Z" \ --patches '[{"op":"replace","path":"metadata.executionName","value":"Anjani Ladia - Email Sent"}]' ``` Use `--patches-file patches.json` instead of inline `--patches` for larger edits. The API still enforces the allowed path list, status transitions, optimistic concurrency, and audit behavior. Completed/canceled/approved/stopped executions may only patch `metadata.executionName`; terminal debug notes, pending reason tags, `currentStepId`, status changes, and mixed patch batches remain blocked. Terminal timelines may patch only top-level `eventSummary` without `--confirm-timeline-id`; terminal `eventContent` or metadata repairs still require exact timeline confirmation. ## Local development Use the built `dist/` entrypoint when testing unpublished CLI changes locally. Do not use `npx -y @agentled/cli` for this, because `npx` resolves the latest published npm package. ```bash cd packages/cli npm run build node dist/index.js --help AGENTLED_URL=http://localhost:8080 node dist/index.js workflows list ``` ## Base URL The CLI defaults to `https://www.agentled.app`. Override it with `AGENTLED_URL` only when testing against another environment.