CLI Architecture

The universal agent interface: domain-driven commands, agent-executable operations, and local-to-remote execution patterns.

Last updated:

On this page

CLI is the new UI.

The same CLI humans use is the CLI agents use. SystemPrompt's command-line interface isn't just a developer tool—it's the universal agent interface for managing AI infrastructure from anywhere.

Why CLI for AI Infrastructure

The Old Way

Traditional AI platforms have:

Web dashboards (humans only)
REST APIs (developers only)
SDKs for each language
Different interfaces for different users

The SystemPrompt Way

One CLI that works for everyone:

Humans type commands in terminals
Agents execute the same commands via MCP tools
Scripts pipe commands together
CI/CD runs commands in automation

┌─────────────────────────────────────────────────────────────────┐
│                      WHO USES THE CLI?                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │  Human  │  │  Agent  │  │ Script  │  │  CI/CD  │           │
│  │Developer│  │(Claude) │  │  Bash   │  │Pipeline │           │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘           │
│       │            │            │            │                  │
│       └────────────┴────────────┴────────────┘                  │
│                           │                                     │
│                           ▼                                     │
│              ┌─────────────────────────┐                        │
│              │   systemprompt CLI      │                        │
│              │                         │                        │
│              │  Same commands          │                        │
│              │  Same output            │                        │
│              │  Same authentication    │                        │
│              └─────────────────────────┘                        │
└─────────────────────────────────────────────────────────────────┘

Domain-Driven Command Structure

Every command follows the pattern:

systemprompt <domain> <subcommand> [args] [flags]

The 8 Domains

Domain	Purpose	Example
`admin`	Users, agents, config, session	`admin agents list`
`infra`	Services, database, jobs, logs	`infra services status`
`core`	Content, playbooks, skills, files	`core content show --slug my-post`
`cloud`	Deployment, sync	`cloud deploy --profile production`
`analytics`	Metrics & insights	`analytics overview`
`web`	Frontend configuration	`web config show`
`plugins`	MCP servers, extensions	`plugins mcp list`
`build`	Build MCP extensions	`build extension`

Domain Examples

# Admin domain - manage agents
systemprompt admin agents list
systemprompt admin agents create --name blog --port 9010
systemprompt admin agents message blog -m "Write a post" --blocking

# Infra domain - manage infrastructure
systemprompt infra services status
systemprompt infra jobs run publish_content
systemprompt infra db status

# Core domain - manage content
systemprompt core content show --slug my-post
systemprompt core playbooks show content_blog
systemprompt core skills list

# Cloud domain - deployment
systemprompt cloud deploy --profile production
systemprompt cloud sync local content --direction to-disk

# Analytics domain - metrics
systemprompt analytics overview
systemprompt analytics agents stats
systemprompt analytics costs breakdown --by agent

Agent-Executable Commands

Here's the key insight: agents can run the same commands you do.

How It Works

Your agent (Claude Code, ChatGPT) connects to SystemPrompt via MCP
SystemPrompt exposes CLI commands as MCP tools
Agent executes commands and receives output
Agent uses output to make decisions

Example: Agent Managing Infrastructure

When you tell Claude Code "create a blog agent":

# Claude Code executes these commands via MCP:
systemprompt admin agents create --name blog --port 9010
systemprompt admin agents edit blog --skill research_content
systemprompt admin agents edit blog --skill content_create
systemprompt admin agents edit blog --mcp-server content-manager
systemprompt admin agents validate blog
systemprompt admin agents edit blog --enable

The agent uses the same commands you would type manually.

MCP Tool Format

Agents call CLI commands through the MCP tool interface:

// MCP: systemprompt_cli
{ "command": "admin agents list" }

// MCP: systemprompt_cli
{ "command": "admin agents message blog -m \"Write about MCP auth\" --blocking" }

// MCP: systemprompt_cli
{ "command": "analytics agents stats" }

Admin Domain - Agent Management

The admin domain handles users, agents, configuration, and sessions.

Agent Lifecycle

# List all agents
systemprompt admin agents list
systemprompt admin agents list --enabled

# Create an agent
systemprompt admin agents create --name blog --port 9010
systemprompt admin agents create --name blog --port 9010 \
  --provider anthropic \
  --model claude-3-5-sonnet-20241022 \
  --enabled

# Configure agent
systemprompt admin agents edit blog --skill research_content
systemprompt admin agents edit blog --mcp-server content-manager
systemprompt admin agents edit blog --system-prompt "You are a blog writer"

# Validate configuration
systemprompt admin agents validate blog

# Enable/disable
systemprompt admin agents edit blog --enable
systemprompt admin agents edit blog --disable

Agent Communication (A2A)

# Send message (fire and forget)
systemprompt admin agents message blog -m "Draft a post about Rust"

# Send message and wait for response
systemprompt admin agents message blog -m "Draft a post about Rust" --blocking

# Send with timeout for long tasks
systemprompt admin agents message blog -m "Research and write" --blocking --timeout 120

# Stream response
systemprompt admin agents message blog -m "Draft a post" --stream

# Continue conversation in context
systemprompt admin agents message blog -m "Continue" --context-id ctx_123 --blocking

# Get async task result
systemprompt admin agents task blog --task-id task_456

Session Management

# Show current session
systemprompt admin session show

# Switch profile
systemprompt admin session use production

# List profiles
systemprompt admin session list

Infra Domain - Infrastructure Management

The infra domain handles services, database, jobs, and logs.

Service Management

# Check status
systemprompt infra services status

# Start services
systemprompt infra services start --all
systemprompt infra services start agent blog

# Stop services
systemprompt infra services stop --all
systemprompt infra services stop agent blog

# Restart
systemprompt infra services restart agent blog
systemprompt infra services restart --agents

Job Scheduler

# List jobs
systemprompt infra jobs list

# Run a job
systemprompt infra jobs run publish_content
systemprompt infra jobs run blog_image_optimization

# View history
systemprompt infra jobs history
systemprompt infra jobs history publish_content

Database Operations

# Status
systemprompt infra db status

# Run migrations
systemprompt infra db migrate

# Execute query (admin only)
systemprompt infra db query "SELECT COUNT(*) FROM users"

Logs

# View logs
systemprompt infra logs
systemprompt infra logs --service api
systemprompt infra logs --service agent --name blog

# Stream logs
systemprompt infra logs --follow
systemprompt infra logs --follow --service agent --name blog

Core Domain - Content & Knowledge

The core domain handles content, playbooks, skills, and files.

Content Management

# List content
systemprompt core content list --source blog
systemprompt core content list --source docs

# Show content
systemprompt core content show --slug my-post --source blog

# Search
systemprompt core content search "MCP authentication"

# Publish
systemprompt core content publish

# Verify
systemprompt core content verify --slug my-post --base-url https://example.com

# Ingest from filesystem
systemprompt core content ingest services/content/blog --source blog

Playbooks

Playbooks are the knowledge base agents read to learn how to interact with the system.

# List playbooks
systemprompt core playbooks list
systemprompt core playbooks list --category cli
systemprompt core playbooks list --category content

# Show playbook
systemprompt core playbooks show guide_start
systemprompt core playbooks show cli_agents
systemprompt core playbooks show content_blog

# Raw output (for piping)
systemprompt core playbooks show content_blog --raw

# Sync playbooks to database
systemprompt core playbooks sync --direction to-db -y

Skills

# List skills
systemprompt core skills list

# Show skill
systemprompt core skills show research_content

# Edit skill
systemprompt core skills edit research_content

# Sync skills
systemprompt core skills sync --direction to-db -y

Contexts

# List contexts
systemprompt core contexts list

# Create context
systemprompt core contexts new --name "blog-mcp-deep-dive"

# Use context
systemprompt core contexts use blog-mcp-deep-dive

# Delete context
systemprompt core contexts delete blog-mcp-deep-dive

Analytics Domain - Metrics & Insights

The analytics domain provides visibility into system performance.

Overview

# Dashboard overview
systemprompt analytics overview

Agent Analytics

# Agent performance
systemprompt analytics agents stats
systemprompt analytics agents trends --days 7
systemprompt analytics agents show blog

Cost Analytics

# Cost breakdown
systemprompt analytics costs summary
systemprompt analytics costs summary --days 30
systemprompt analytics costs breakdown --by agent
systemprompt analytics costs breakdown --by model

Content Analytics

# Content performance
systemprompt analytics content stats
systemprompt analytics content trends --days 30
systemprompt analytics content popular --limit 20

Request Analytics

# AI request stats
systemprompt analytics requests stats
systemprompt analytics requests list --limit 50 --model claude
systemprompt analytics requests models

Cloud Domain - Deployment

The cloud domain handles deployment and synchronisation.

Deployment

# Deploy to cloud
systemprompt cloud deploy --profile production

# Check deployment status
systemprompt cloud status

Synchronisation

# Sync content from database to filesystem
systemprompt cloud sync local content --direction to-disk --source blog -y

# Sync content from filesystem to database
systemprompt cloud sync local content --direction to-db --source blog -y

Profile Management

# Create profile
systemprompt cloud profile create production

# List profiles
systemprompt cloud profile list

# Use profile
systemprompt cloud profile use production

Pipe-Friendly Output

CLI output is designed for scripting and automation.

JSON Output

# Get JSON output
systemprompt admin agents list --output json | jq '.[] | .name'

# Parse in scripts
AGENT_COUNT=$(systemprompt admin agents list --output json | jq length)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Authentication required
4	Resource not found

Scripting Examples

#!/bin/bash

# Create and configure an agent
systemprompt admin agents create --name blog --port 9010 || exit 1
systemprompt admin agents edit blog --skill research_content
systemprompt admin agents edit blog --skill content_create
systemprompt admin agents validate blog || {
  echo "Validation failed"
  systemprompt admin agents delete blog -y
  exit 1
}
systemprompt admin agents edit blog --enable

echo "Agent blog is ready"

Local-to-Remote Execution

The same CLI works locally and in production.

Local Development

# Use local profile
systemprompt admin session use local

# Commands execute against local database
systemprompt admin agents list

Production

# Use production profile
systemprompt admin session use production

# Same commands execute against production
systemprompt admin agents list

Profile-Based Routing

# Execute against specific profile
systemprompt --profile production admin agents list
systemprompt --profile staging admin agents list
systemprompt --profile local admin agents list

Next Steps

Self-Learning Architecture — The agentic feedback loop
Complete Example — Full workflow walkthrough
CLI Reference — Complete command reference