@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

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 and Hermes currently have skill installation support, but not MCP auto-config support in agentled setup. For those clients, authenticate once, install the matching skill bundle, and configure MCP using the client's native MCP settings:

npx -y @agentled/cli auth login
npx -y @agentled/cli skills install --target openclaw
npx -y @agentled/cli skills install --target hermes

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.

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

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.

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

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

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

# Patch execution metadata, for example to relabel a stuck/test run
agentled executions patch-execution-fields <workflowId> <executionId> \
  --reason "Clarify execution name during incident review" \
  --expected-updated-at "2026-05-05T10:00:00.000Z" \
  --patches '[{"op":"replace","path":"metadata.executionName","value":"Recovered test run"}]'

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.

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.