@agentled/cli/README.md

CLI for Agentled — manage workflows, apps, and knowledge from the command line. Zero context-window cost for AI agents.

# @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 <workflowId> --format json
agentled use-cases get <key-or-workflowGraphId> --format json
agentled knowledge text <guideKey> --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 <workspace>  # 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 <id> --output workflow.json
agentled workflows diff <id> --file workflow.json
agentled workflows replace <id> --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 <id> --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 <id>
agentled workflows delete <id> --confirm-token <token-from-preview>
```

## 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 <workflowId>
```

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 <workflowId> --input '{"startupUrl":"https://acme.com"}'

# Force a real run that ignores all step mocks (consumes real credits)
agentled wf start <workflowId> --input '{"startupUrl":"https://acme.com"}' --no-mocks

# Explicitly opt in to mocks (same as default, useful in scripts)
agentled wf start <workflowId> --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 <workflowId> --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 <turnId> --format json

# Find the execution if the turn only identifies the workflow or input row.
agentled executions list <workflowId> --limit 5 --direction desc --format json

# Poll this command until status is completed, failed, stopped, or canceled.
agentled executions get <workflowId> <executionId> --format json

# Inspect the result-producing step instead of trusting the initial handoff text.
agentled executions step-output <workflowId> <executionId> <stepId> --format json

# Deliver the terminal outcome through the same conversation.
agentled chat --session-id <sessionId> \
  "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 <workflowId> <executionId> <timelineId> \
  --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 <workflowId> <executionId> <timelineId> \
  --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 <workflowId> <executionId> \
  --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.