@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

agentled auth login
agentled auth current
agentled workflows list
agentled workspace info
agentled workspace company-profile

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

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

# Update + validate (default)
agentled workflows update <id> --file updates.json

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 8 bundled workflow patterns
agentled examples

# Print one pattern (by slug, number, or keyword)
agentled examples trigger-design
agentled examples 04                # loops
agentled examples dedup

# 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

# 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 | | 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 | | 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"]}'

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

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.

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.