sf-agent-framework/docs/07-cli-commands/README.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# CLI Commands Reference

## Overview

The SF-Agent Framework CLI provides comprehensive commands for managing Salesforce development workflows. All commands follow a consistent pattern and support both interactive and scriptable modes.

## Command Structure

```
sf-agent [global-options] <command> [subcommand] [options] [arguments]
```

### Global Options

```bash
--help, -h          Show help
--version, -v       Show version
--verbose           Verbose output
--quiet, -q         Suppress output
--debug             Debug mode
--profile <name>    Use configuration profile
--config <path>     Use custom config file
--no-color          Disable colored output
--json              JSON output format
--dry-run           Preview without executing
--force             Skip confirmations
```

## Core Commands

### `sf-agent install`

Install and initialize the framework in your project.

```bash
# Interactive installation
sf-agent install

# Non-interactive with defaults
sf-agent install --non-interactive

# Custom installation
sf-agent install \
  --project-type brownfield \
  --ide cursor \
  --two-phase \
  --org myorg

# Options
--project-type <type>    Project type (greenfield|brownfield|package)
--ide <ide>              Primary IDE (cursor|vscode|claude-code|idea)
--two-phase              Enable two-phase development
--org <alias>            Salesforce org alias
--skip-git               Skip git hooks installation
--minimal                Minimal installation
```

### `sf-agent init`

Initialize framework in existing project.

```bash
# Basic initialization
sf-agent init

# With specific configuration
sf-agent init --from-template enterprise

# Options
--from-template <name>   Use configuration template
--import <file>          Import configuration from file
--force                  Overwrite existing configuration
```

### `sf-agent doctor`

Check framework health and configuration.

```bash
# Full diagnostic
sf-agent doctor

# Specific checks
sf-agent doctor --check dependencies
sf-agent doctor --check configuration
sf-agent doctor --check connectivity

# Auto-fix issues
sf-agent doctor --fix

# Options
--check <type>           Specific check (all|dependencies|configuration|connectivity)
--fix                    Attempt to fix issues
--verbose                Show detailed diagnostics
```

## Phase Management

### `sf-agent phase`

Manage development phases (planning/development).

```bash
# Show current phase
sf-agent phase

# Switch phase
sf-agent phase planning
sf-agent phase development

# Phase with context info
sf-agent phase --info

# Options
--info                   Show phase details
--context-limit <n>      Override context limit
--agents <list>          Override default agents
```

## Agent Commands

### `sf-agent agent`

Work with specific agents.

```bash
# List all agents
sf-agent agent list

# Use specific agent
sf-agent agent sf-developer
sf-agent agent sf-architect

# Get agent info
sf-agent agent info sf-developer

# Run agent task
sf-agent agent sf-developer --task "implement login"

# Options
--list                   List available agents
--info                   Show agent information
--task <description>     Run specific task
--context <file>         Load additional context
--interactive            Interactive mode
```

### `sf-agent agents`

Manage multiple agents.

```bash
# Build agent bundles
sf-agent agents build

# Update agents
sf-agent agents update

# Validate agents
sf-agent agents validate

# Options
--only <list>            Process specific agents
--parallel               Process in parallel
--force                  Force rebuild
```

## Workflow Commands

### `sf-agent workflow`

Execute predefined workflows.

```bash
# List available workflows
sf-agent workflow list

# Start workflow
sf-agent workflow requirements
sf-agent workflow feature-planning
sf-agent workflow implementation

# Interactive workflow selection
sf-agent workflow

# Custom workflow
sf-agent workflow --file ./my-workflow.yaml

# Options
--list                   List available workflows
--file <path>            Use custom workflow file
--interactive            Force interactive mode
--auto                   Non-interactive mode
--step <n>               Start from specific step
--validate               Validate workflow only
```

### `sf-agent workflows`

Manage workflow library.

```bash
# Create new workflow
sf-agent workflows create

# Edit workflow
sf-agent workflows edit planning-workflow

# Import workflow
sf-agent workflows import ./workflow.yaml

# Export workflow
sf-agent workflows export planning-workflow

# Options
--template <name>        Use workflow template
--validate               Validate workflows
```

## Story Management

### `sf-agent story`

Work with user stories.

```bash
# List stories
sf-agent story list

# Get next story
sf-agent story next

# Implement story
sf-agent story implement STORY-001

# Complete story
sf-agent story complete STORY-001

# Story details
sf-agent story info STORY-001

# Options
--status <status>        Filter by status (pending|in-progress|completed)
--assign                 Assign to current user
--validate               Validate story implementation
```

### `sf-agent stories`

Manage story queue.

```bash
# Generate stories from requirements
sf-agent stories generate

# Import stories
sf-agent stories import ./stories.yaml

# Prioritize stories
sf-agent stories prioritize

# Options
--from <file>            Source file for generation
--count <n>              Number of stories to generate
--epic <name>            Group stories by epic
```

## Task Execution

### `sf-agent task`

Execute specific tasks.

```bash
# Document generation
sf-agent task document-apex
sf-agent task document-lwc
sf-agent task document-flows

# Code generation
sf-agent task create-apex-class --name AccountService
sf-agent task create-lwc --name accountList
sf-agent task create-trigger --object Account

# Analysis tasks
sf-agent task analyze-code
sf-agent task security-scan
sf-agent task performance-check

# Options
--name <name>            Resource name
--object <object>        Salesforce object
--template <template>    Use specific template
--output <path>          Output directory
```

### `sf-agent tasks`

Manage task library.

```bash
# List available tasks
sf-agent tasks list

# Search tasks
sf-agent tasks search "apex"

# Create custom task
sf-agent tasks create

# Options
--category <cat>         Filter by category
--agent <agent>          Filter by agent
```

## Build Commands

### `sf-agent build`

Build framework artifacts.

```bash
# Build everything
sf-agent build

# Build specific targets
sf-agent build web
sf-agent build agents
sf-agent build teams

# Build for specific platform
sf-agent build web --target chatgpt
sf-agent build web --target gemini

# Options
--target <target>        Build target
--output <path>          Output directory
--compress               Compress output
--include-docs           Include documentation
--minimal                Minimal build
```

## Validation Commands

### `sf-agent validate`

Run validation checks.

```bash
# Validate everything
sf-agent validate

# Specific validations
sf-agent validate security
sf-agent validate quality
sf-agent validate performance
sf-agent validate compliance

# Validate specific files
sf-agent validate --files "src/**/*.cls"

# Options
--type <type>            Validation type
--files <pattern>        File pattern
--fix                    Auto-fix issues
--report <format>        Report format (json|html|markdown)
```

## Testing Commands

### `sf-agent test`

Run tests.

```bash
# Run all tests
sf-agent test

# Run specific test class
sf-agent test --class AccountServiceTest

# Run test suite
sf-agent test --suite regression

# Generate tests
sf-agent test generate --class AccountService

# Options
--class <name>           Test class name
--suite <name>           Test suite name
--coverage               Show coverage report
--parallel               Run tests in parallel
--generate               Generate missing tests
```

## Deployment Commands

### `sf-agent deploy`

Deploy to Salesforce org.

```bash
# Deploy all changes
sf-agent deploy

# Deploy specific components
sf-agent deploy --components "src/classes/*.cls"

# Validate deployment
sf-agent deploy --check-only

# Deploy to specific org
sf-agent deploy --org production

# Options
--org <alias>            Target org
--check-only             Validation only
--test-level <level>     Test level (NoTestRun|RunSpecifiedTests|RunLocalTests|RunAllTestsInOrg)
--rollback-on-error      Auto rollback on error
--wait <minutes>         Deployment timeout
```

## Documentation Commands

### `sf-agent document`

Generate documentation.

```bash
# Document everything
sf-agent document

# Document specific types
sf-agent document apex
sf-agent document lwc
sf-agent document flows
sf-agent document objects

# Generate specific docs
sf-agent document --type user-guide
sf-agent document --type api-reference
sf-agent document --type architecture

# Options
--type <type>            Documentation type
--format <format>        Output format (markdown|html|pdf)
--output <path>          Output directory
--include-private        Include private members
```

## Configuration Commands

### `sf-agent config`

Manage configuration.

```bash
# Show configuration
sf-agent config list
sf-agent config get <key>

# Set configuration
sf-agent config set <key> <value>
sf-agent config set organization.alias myorg

# Edit configuration
sf-agent config edit

# Reset configuration
sf-agent config reset

# Options
--global                 Global configuration
--profile <name>         Use specific profile
--validate               Validate configuration
--export                 Export configuration
```

## Utility Commands

### `sf-agent handoff`

Manage agent handoffs.

```bash
# Create handoff
sf-agent handoff create \
  --from sf-architect \
  --to sf-developer \
  --artifacts "requirements.md,architecture.md"

# List handoffs
sf-agent handoff list

# Accept handoff
sf-agent handoff accept HANDOFF-001

# Options
--from <agent>           Source agent
--to <agent>             Target agent
--artifacts <list>       Artifacts to handoff
--message <msg>          Handoff message
```

### `sf-agent shard`

Shard large documents.

```bash
# Shard document
sf-agent shard docs/requirements.md

# Shard with custom size
sf-agent shard docs/architecture.md --size 5000

# Options
--size <tokens>          Shard size in tokens
--output <dir>           Output directory
--format <format>        Output format (story|snippet|chunk)
```

### `sf-agent bundle`

Create web bundles.

```bash
# Create ChatGPT bundle
sf-agent bundle chatgpt

# Create Gemini bundle
sf-agent bundle gemini

# Custom bundle
sf-agent bundle custom --config ./bundle-config.yaml

# Options
--config <file>          Bundle configuration
--output <path>          Output path
--compress               Compress bundle
```

### `sf-agent context`

Manage context.

```bash
# Show context status
sf-agent context status

# Clear context
sf-agent context clear

# Load context
sf-agent context load ./context-file.md

# Save context
sf-agent context save

# Options
--show-loaded            Show loaded files
--show-usage             Show token usage
--optimize               Optimize context
```

### `sf-agent cache`

Manage cache.

```bash
# Show cache status
sf-agent cache status

# Clear cache
sf-agent cache clear

# Clear specific cache
sf-agent cache clear --type context
sf-agent cache clear --type artifacts

# Options
--type <type>            Cache type (all|context|artifacts|metrics)
--older-than <days>      Clear items older than N days
```

### `sf-agent metrics`

View metrics and analytics.

```bash
# Show metrics dashboard
sf-agent metrics

# Specific metrics
sf-agent metrics tokens
sf-agent metrics performance
sf-agent metrics costs

# Export metrics
sf-agent metrics export --format csv

# Options
--period <period>        Time period (today|week|month|all)
--format <format>        Export format (json|csv|html)
--agent <agent>          Filter by agent
```

### `sf-agent update`

Update framework.

```bash
# Check for updates
sf-agent update --check

# Update to latest
sf-agent update

# Update to specific version
sf-agent update --version 4.1.0

# Options
--check                  Check only
--version <ver>          Specific version
--force                  Force update
--backup                 Backup before update
```

### `sf-agent migrate`

Migrate between versions.

```bash
# Run migration wizard
sf-agent migrate

# Specific migration
sf-agent migrate v3-to-v4

# Options
--from <version>         Source version
--to <version>           Target version
--backup                 Create backup
--validate               Validate only
```

## Interactive Mode

### `sf-agent interactive`

Start interactive session.

```bash
# Start interactive mode
sf-agent interactive

# With specific context
sf-agent interactive --context ./project-context.md

# Options
--context <file>         Load context file
--mode <mode>            Interaction mode (guided|expert)
--history                Load command history
```

## Batch Operations

### Running Multiple Commands

```bash
# From file
sf-agent batch --file commands.txt

# Piped commands
echo "phase planning
workflow requirements
phase development" | sf-agent batch

# Options
--file <file>            Commands file
--stop-on-error          Stop on first error
--parallel               Run in parallel where possible
```

## Scripting Support

### Shell Scripts

```bash
#!/bin/bash
# Example: Automated workflow

# Set phase
sf-agent phase planning

# Run planning workflow
sf-agent workflow requirements

# Transition to development
sf-agent phase development

# Implement stories
for story in $(sf-agent story list --status pending --json | jq -r '.[].id'); do
  sf-agent story implement "$story"
  sf-agent test --class "*${story}*"
  sf-agent story complete "$story"
done

# Deploy
sf-agent deploy --check-only
sf-agent deploy
```

### Node.js Scripts

```javascript
#!/usr/bin/env node
const { CLI } = require('sf-agent-framework');

async function automatedWorkflow() {
  const cli = new CLI();

  // Set phase
  await cli.execute('phase', 'planning');

  // Run workflow
  await cli.execute('workflow', 'requirements');

  // Get stories
  const stories = await cli.execute('story', 'list', {
    status: 'pending',
    json: true,
  });

  // Implement each story
  for (const story of stories) {
    await cli.execute('story', 'implement', story.id);
    await cli.execute('test', { class: `*${story.id}*` });
    await cli.execute('story', 'complete', story.id);
  }

  // Deploy
  await cli.execute('deploy', { checkOnly: true });
  await cli.execute('deploy');
}

automatedWorkflow().catch(console.error);
```

## Command Aliases

Create custom aliases for frequently used commands:

```bash
# In ~/.bashrc or ~/.zshrc
alias sfa='sf-agent'
alias sfap='sf-agent phase'
alias sfaw='sf-agent workflow'
alias sfas='sf-agent story'
alias sfab='sf-agent build'
alias sfad='sf-agent deploy'

# Complex aliases
alias sfa-quick-deploy='sf-agent validate && sf-agent test && sf-agent deploy'
alias sfa-full-build='sf-agent build web && sf-agent build agents'
```

## Exit Codes

The CLI uses standard exit codes:

| Code | Meaning             |
| ---- | ------------------- |
| 0    | Success             |
| 1    | General error       |
| 2    | Misuse of command   |
| 3    | Configuration error |
| 4    | Connection error    |
| 5    | Validation error    |
| 6    | Deployment error    |
| 7    | Test failure        |
| 8    | Build error         |
| 126  | Permission denied   |
| 127  | Command not found   |

## Tips and Tricks

### 1. Command Completion

```bash
# Enable bash completion
sf-agent completion bash > ~/.sf-agent-completion.bash
source ~/.sf-agent-completion.bash

# Enable zsh completion
sf-agent completion zsh > ~/.sf-agent-completion.zsh
source ~/.sf-agent-completion.zsh
```

### 2. Quick Commands

```bash
# Quick status check
sf-agent status

# Quick validation
sf-agent validate --quick

# Quick test
sf-agent test --quick
```

### 3. Debugging

```bash
# Debug mode
SF_AGENT_DEBUG=true sf-agent workflow

# Verbose output
sf-agent --verbose workflow

# Dry run
sf-agent --dry-run deploy
```

### 4. JSON Output

```bash
# Get JSON output for scripting
sf-agent story list --json | jq '.[] | select(.status=="pending")'

# Format JSON output
sf-agent config list --json | python -m json.tool
```

## Getting Help

```bash
# General help
sf-agent --help

# Command help
sf-agent workflow --help

# Interactive help
sf-agent help

# Man page (if installed)
man sf-agent
```

---

_Last Updated: 2025-08-11_
_Version: 4.0.0_