cli/docs/cli-reference.md

CLI Reference

This document provides a comprehensive reference for all available commands in the Core CLI.

Overview

The Core CLI is a unified development tool that provides commands for:

• AI/ML operations and agent management
• Multi-repository development workflows
• Infrastructure and deployment management
• Security monitoring and analysis
• Data collection and RAG systems
• Cryptographic utilities
• Testing and quality assurance

Quick Command Index

Command	Category	Description
ai	AI/ML	Agentic task management and agent configuration
collect	Data	Collect data from external sources
config	Config	Configuration management
crypt	Security	Cryptographic utilities
daemon	Service	Background service management
deploy	DevOps	Coolify deployment management
dev	Development	Multi-repo development workflow
docs	Documentation	Documentation management
doctor	Utilities	Environment verification
forge	Git	Forgejo instance management
git	Git	Root-level git workflow commands
gitea	Git	Gitea instance management
go	Development	Go development commands
help	Utilities	Help documentation
lab	Monitoring	Homelab monitoring dashboard
mcp	AI/ML	Model Context Protocol server
ml	AI/ML	ML inference and training pipeline
monitor	Security	Security monitoring
plugin	Utilities	Plugin management
prod	DevOps	Production infrastructure management
qa	Development	Quality assurance workflow
rag	AI/ML	RAG system for embeddings and semantic search
security	Security	Security management
session	Utilities	Session recording and replay
setup	Utilities	Workspace setup and bootstrap
test	Development	Test running
unifi	Networking	UniFi network management
update	Utilities	CLI self-update
vm	DevOps	LinuxKit VM management
workspace	Config	Workspace configuration

Detailed Command Reference

ai

Agentic task management and agent configuration

Manage AI agents, tasks, and integrations with external services.

Subcommands:

• agent - Manage AgentCI dispatch targets
  • add - Add a new dispatch target
  • list - List all configured targets
  • status - Show target status
  • logs - View target logs
  • setup - Initial target setup
  • remove - Remove a target
• tasks - Agentic task management
  • list - List all tasks
  • view - View task details
  • update - Update task status
  • complete - Mark task as complete
• git - Git integration for tasks
  • commit - Create commits for tasks
  • PR - Create pull requests
• metrics - Task metrics tracking
• commands - AI command management
• updates - Task updates
• ratelimits - Rate limiting configuration
• dispatch - Task dispatch management

Examples:

# List all AI tasks
core ai tasks list

# View task details
core ai tasks view TASK-123

# Add dispatch target
core ai agent add --name my-agent --url https://api.example.com

---

collect

Collect data from various sources

Data collection tools for gathering information from external sources like GitHub, forums, and research papers.

Persistent Flags:

• --output, -o - Output directory
• --verbose, -v - Verbose output
• --dry-run - Show what would happen without executing

Subcommands:

• github - Collect data from GitHub repositories
• bitcointalk - Collect from BitcoinTalk forum
• market - Collect market data
• papers - Collect research papers
• excavate - Deep excavation of sources
• process - Process collected data
• dispatch - Dispatch collection jobs

Examples:

# Collect GitHub data
core collect github --org myorg --output ./data

# Collect research papers
core collect papers --query "machine learning" --output ./papers

---

config

Manage configuration

Manage Core CLI configuration values stored in ~/.core/config.yaml.

Subcommands:

• get - Get a config value
• set - Set a config value
• list - List all config values
• path - Show config file path

Examples:

# Get a config value
core config get dev.editor

# Set a config value
core config set dev.editor vim

# List all config
core config list

# Show config file location
core config path

See also: Configuration Reference

---

crypt

Cryptographic utilities

Encrypt, decrypt, hash, and checksum files and data.

Subcommands:

• hash - Hash files or data
• encrypt - Encrypt files or data
• keygen - Generate cryptographic keys
• checksum - Generate and verify checksums

Examples:

# Hash a file
core crypt hash --file myfile.txt

# Generate a PGP key
core crypt keygen --name "John Doe" --email john@example.com

# Encrypt a file
core crypt encrypt --file secret.txt --recipient john@example.com

# Generate checksums
core crypt checksum --file release.tar.gz

---

daemon

Start the core daemon

Start Core daemon for long-running services like MCP.

Flags:

• --mcp-transport, -t - MCP transport (stdio, tcp, socket)
• --mcp-addr, -a - Listen address for TCP/socket
• --health-addr - Health check endpoint address
• --pid-file - PID file path

Environment Variables:

• CORE_MCP_TRANSPORT - MCP transport type
• CORE_MCP_ADDR - MCP listen address
• CORE_HEALTH_ADDR - Health check address
• CORE_PID_FILE - PID file location

Examples:

# Start daemon with MCP on stdio
core daemon

# Start daemon with TCP MCP server
core daemon --mcp-transport tcp --mcp-addr :9100

# Start with health endpoint
core daemon --health-addr :8080

---

deploy

Deployment infrastructure management

Manage Coolify deployments and infrastructure.

Flags:

• --url - Coolify instance URL
• --token - API token
• --json - JSON output format

Subcommands:

• servers - List Coolify servers
• projects - List projects
• apps - List applications
• databases / dbs / db - List databases
• services - List services
• team - Show team info
• call - Call arbitrary Coolify API operations

Examples:

# List all servers
core deploy servers

# List applications
core deploy apps

# Call custom API endpoint
core deploy call --method GET --path /api/v1/status

---

dev

Development workflow commands

Multi-repository development workflows with health checks, commits, and CI monitoring.

Subcommands:

• work - Combined status, commit, and push workflow
• health - Quick health check across repos
• commit - Claude-assisted commit message generation
• push - Push repos with unpushed commits
• pull - Pull repos behind remote
• issues - List open issues
• reviews - List PRs needing review
• ci - Check GitHub Actions CI status
• impact - Analyze dependency impact
• workflow - CI/workflow management
• api - API synchronization
• vm - VM management
  • install, boot, stop, status, shell, serve, test, claude, update
• file-sync - Sync files across repos (safe for AI agents)
• apply - Run commands across repos (safe for AI agents)

Examples:

# Full workflow: status, commit, push
core dev work

# Health check all repos
core dev health

# Claude-assisted commit
core dev commit

# List open issues
core dev issues

# Check CI status
core dev ci

---

docs

Documentation management

Manage project documentation.

Subcommands:

• sync - Sync documentation
• list - List documentation
• commands - Command documentation
• scan - Scan for documentation

Examples:

# Sync documentation
core docs sync

# List available docs
core docs list

---

doctor

Check development environment

Verify required tools and dependencies are installed and configured.

Flags:

• --verbose - Show detailed check results

Checks:

• Required tools validation (Go, Git, Task, etc.)
• Optional tools validation
• GitHub SSH access
• GitHub CLI authentication
• Workspace validation

Examples:

# Quick environment check
core doctor

# Verbose check with details
core doctor --verbose

---

forge

Forgejo instance management

Manage Forgejo repositories, issues, and pull requests.

Subcommands:

• config - Configure Forgejo connection
• status - Show instance status and version
• repos - List repositories
• issues - List and create issues
• prs - List pull requests
• migrate - Migrate repos from external services
• sync - Sync GitHub repos to upstream branches
• orgs - List organizations
• labels - List and create labels

Examples:

# Configure Forgejo
core forge config --url https://forge.example.com --token YOUR_TOKEN

# List repositories
core forge repos

# List issues
core forge issues

# Create an issue
core forge issues create --title "Bug fix" --body "Description"

---

git

Root-level git workflow commands

Git operations wrapper (imports commands from dev package).

Subcommands:

• health - Show repo status
• commit - Claude-assisted commits
• push - Push repositories
• pull - Pull repositories
• work - Combined workflow
• file-sync - Safe file synchronization
• apply - Safe command execution

Examples:

# Check repo health
core git health

# Claude-assisted commit
core git commit

---

gitea

Gitea instance management

Manage Gitea repositories and integrations.

Subcommands:

• config - Configure Gitea connection
• repos - List repositories
• issues - List and create issues
• prs - List pull requests
• mirror - Create GitHub-to-Gitea mirrors
• sync - Sync GitHub repos to upstream branches

Examples:

# Configure Gitea
core gitea config --url https://gitea.example.com

# Create GitHub mirror
core gitea mirror --repo owner/repo

---

go

Go development utilities

Go-specific development tools for testing, coverage, and quality assurance.

Subcommands:

• qa - Quality assurance checks
• test - Run tests
• cov - Code coverage analysis
• fmt - Code formatting
• lint - Linting
• install - Install Go tools
• mod - Module management
• work - Workspace management
• fuzz - Fuzz testing

Examples:

# Run QA checks
core go qa

# Run tests with coverage
core go cov

# Format code
core go fmt

# Run specific test
core go test --run TestMyFunction

---

help

Display help documentation

Access built-in help documentation.

Flags:

• --search, -s - Search help topics

Examples:

# Show help
core help

# Search help topics
core help --search "configuration"

---

lab

Homelab monitoring dashboard

Real-time monitoring of machines, training runs, models, and services.

Subcommands:

• serve - Start lab dashboard web server
  • --bind - HTTP listen address

Examples:

# Start dashboard on default port
core lab serve

# Start on custom port
core lab serve --bind :8080

---

mcp

Model Context Protocol server

MCP server providing file operations, RAG, and metrics tools for AI assistants.

Subcommands:

• serve - Start the MCP server
  • --workspace, -w - Restrict file operations to directory

Environment Variables:

• MCP_ADDR - TCP address (e.g., localhost:9999). If not set, uses stdio.

Transport:

• stdio (default) - For Claude Code integration
• TCP - Set via MCP_ADDR environment variable

Examples:

# Start with stdio (for Claude Code)
core mcp serve

# Start with workspace restriction
core mcp serve --workspace /path/to/project

# Start TCP server
MCP_ADDR=localhost:9999 core mcp serve

See also: MCP Integration

---

ml

ML inference, scoring, and training pipeline

Commands for model scoring, probe evaluation, data export, and format conversion.

Persistent Flags:

• --api-url - OpenAI-compatible API URL
• --judge-url - Judge model API URL (Ollama)
• --judge-model - Judge model name
• --influx - InfluxDB URL
• --influx-db - InfluxDB database
• --db - DuckDB database path
• --model - Model name for API

Subcommands:

• score - Score responses with heuristic and LLM judges
• probe - Run capability and content probes against a model
• export - Export golden set to training formats
• expand - Generate expansion responses
• status - Show training and generation progress
• gguf - Convert MLX LoRA adapter to GGUF format
• convert - Convert MLX LoRA adapter to PEFT format
• agent - Run the scoring agent daemon
• worker - Run a distributed worker node
• serve - Start OpenAI-compatible inference server
• inventory - Show DuckDB table inventory
• query - Run ad-hoc SQL against DuckDB
• metrics - Push golden set stats to InfluxDB
• ingest - Ingest benchmark scores to InfluxDB
• normalize - Deduplicate seeds into expansion prompts
• seed-influx - Migrate golden set from DuckDB to InfluxDB
• consolidate - Pull and merge response JSONL files
• import-all - Import all LEM data into DuckDB
• approve - Filter scored expansions into training JSONL
• publish - Upload Parquet dataset to HuggingFace Hub
• coverage - Analyze seed coverage by region and domain

Examples:

# Score model responses
core ml score --model gpt-4

# Run capability probes
core ml probe --api-url http://localhost:8000

# Export training data
core ml export --format jsonl

---

monitor

Security finding aggregation

Aggregate GitHub code scanning, Dependabot, and secret scanning alerts.

Flags:

• --repo - Specific repository
• --all - All repositories
• --severity - Filter by severity
• --json - JSON output

Examples:

# Monitor all repos
core monitor --all

# Monitor specific repo with high severity
core monitor --repo owner/repo --severity high

---

plugin

Manage plugins

Install and manage CLI plugins.

Subcommands:

• install - Install a plugin from GitHub
• list - List installed plugins
• info - Show detailed plugin information
• update - Update a plugin or all plugins
• remove - Remove an installed plugin

Examples:

# Install plugin
core plugin install owner/repo

# List installed
core plugin list

# Update all
core plugin update

---

prod

Production infrastructure management

Manage Host UK production infrastructure.

Flags:

• --config - Path to infra.yaml

Subcommands:

• status - Show infrastructure health
• setup - Phase 1: discover topology, create LB, configure DNS
• dns - Manage DNS records via CloudNS
• lb - Manage Hetzner load balancer
• ssh - SSH into a production host

Examples:

# Check infrastructure status
core prod status

# Setup infrastructure
core prod setup

# SSH to host
core prod ssh web1

---

qa

Quality assurance workflow

Verify work (CI status, reviews, issues) - complements 'dev' which is about doing work.

Subcommands:

• watch - Monitor GitHub Actions after push
• review - PR review status with actionable steps
• health - Aggregate CI health across repos
• issues - Intelligent issue triage
• docblock - Documentation block validation

Examples:

# Watch CI after push
core qa watch

# Check PR review status
core qa review

# Health check across repos
core qa health

---

rag

RAG system for embeddings and semantic search

Retrieval-Augmented Generation system using Qdrant and Ollama.

Persistent Flags:

• --qdrant-host - Qdrant host (default: localhost)
• --qdrant-port - Qdrant port (default: 6334)
• --ollama-host - Ollama host (default: localhost)
• --ollama-port - Ollama port (default: 11434)
• --model - Embedding model (default: nomic-embed-text)
• --verbose, -v - Verbose output

Subcommands:

• ingest - Ingest documents into collections
• query - Query collections
• collections - Manage collections (list, stats, delete)

Examples:

# Ingest documents
core rag ingest --collection docs --path ./documentation

# Query collection
core rag query --collection docs --query "how to install"

# List collections
core rag collections list

---

security

Security management

Security operations and scanning.

Subcommands:

• jobs - Security job management
• secrets - Secrets management
• alerts - Security alerts
• scan - Security scanning

Examples:

# List security alerts
core security alerts

# Run security scan
core security scan

---

session

Session recording and replay

Record and replay CLI sessions with timeline generation.

Subcommands:

• list - List recent sessions
• replay - Generate HTML timeline (and optional MP4) from session
  • --mp4 - Generate MP4 video
  • --output - Output directory
• search - Search across session transcripts

Examples:

# List sessions
core session list

# Replay session as HTML
core session replay SESSION_ID

# Replay with MP4
core session replay SESSION_ID --mp4

---

setup

Workspace setup and bootstrap

Set up development workspace from registry.

Flags:

• --registry - Registry path
• --only - Specific setup targets
• --dry-run - Show what would happen
• --all - Setup all targets
• --name - Target name
• --build - Build after setup

Subcommands:

• wizard - Interactive setup wizard
• github - GitHub setup
• registry - Registry setup
• ci - CI setup
• repo - Repository setup
• bootstrap - Bootstrap new workspace

Examples:

# Interactive setup
core setup wizard

# Setup from registry
core setup --registry repos.yaml --all

# Bootstrap workspace
core setup bootstrap

---

test

Run tests

Execute Go tests with various options.

Flags:

• --verbose - Verbose output
• --coverage - Generate coverage report
• --short - Run short tests only
• --pkg - Specific package
• --run - Test filter pattern
• --race - Enable race detector
• --json - JSON output

Examples:

# Run all tests
core test

# Run with coverage
core test --coverage

# Run specific test
core test --run TestMyFunction

# Race detection
core test --race

---

unifi

UniFi network management

Manage UniFi network devices and configuration.

Subcommands:

• config - Configure UniFi connection
• clients - List connected clients
• devices - List infrastructure devices
• sites - List controller sites
• networks - List network segments and VLANs
• routes - List gateway routing table

Examples:

# Configure UniFi
core unifi config --url https://192.168.1.1

# List clients
core unifi clients

# List devices
core unifi devices

---

update

Update core CLI to latest version

Self-update the Core CLI binary.

Flags:

• --channel - Release channel (stable, beta, alpha, dev)
• --force - Force update even if on latest
• --check - Check without applying

Subcommands:

• check - Check for available updates

Channels:

• stable - Stable releases
• beta - Beta releases
• alpha - Alpha releases
• dev - Rolling development releases

Examples:

# Update to latest stable
core update

# Check for updates
core update check

# Update to beta channel
core update --channel beta

---

vm

Virtual machine management

Manage LinuxKit VMs for testing and development.

Subcommands:

• run - Run a VM
• ps - List running VMs
• stop - Stop a VM
• logs - View VM logs
• exec - Execute command in VM
• templates - Manage VM templates

Examples:

# Run VM
core vm run my-vm

# List running VMs
core vm ps

# Execute command
core vm exec my-vm -- ls -la

---

workspace

Manage workspace configuration

Configure workspace-specific settings.

Subcommands:

• active - Show or set active package
• task - Workspace task management
• agent - Workspace agent configuration

Examples:

# Show active workspace
core workspace active

# Set active package
core workspace active --set ./pkg/mypackage

---

Common Patterns

Flags and Options

Common Persistent Flags:

• --verbose, -v - Verbose output
• --dry-run - Show what would happen without executing
• --output, -o - Output file or directory
• --json - JSON output format
• --help, -h - Show help for command

Environment Variables

Many commands respect environment variables. See Environment Variables for a complete list.

Configuration Files

Commands load configuration from:

1. Command-line flags (highest priority)
2. Environment variables
3. Configuration file (~/.core/config.yaml)
4. Default values (lowest priority)

See Configuration Reference for details.

Getting Help

For command-specific help:

core <command> --help
core <command> <subcommand> --help

For general help:

core help
core --help