@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

npm install -g @agentled/cli

Quick Start

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:

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:

# 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:

npx -y @agentled/[email protected] auth login
npx -y @agentled/cli skills install --target openclaw

Use --reauth when switching workspaces or recovering from a failed browser login:

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 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:

# 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:

npx -y @agentled/[email protected] auth login
npx -y @agentled/[email protected] auth status
npx -y @agentled/[email protected] 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.

# 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:

agentled auth login --skip-skills

Manage the skill manually with the agentled skills subcommands:

# 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.

# 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.

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).

# 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:

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.

# 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. 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.

# 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

# 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.

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:

# 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.

# 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.

# 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.

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.