Version Set CLI Reference

Complete forge version-set, forge service, and forge asset command reference for listing, pinning, promoting, and rolling back Amigo service version sets.

This page is the Agent Forge CLI reference for working with version sets: the forge version-set commands that create, compare, promote, and roll back version sets, plus the forge service and forge asset commands you use to discover services and asset versions before pinning them. For the concepts behind version sets and the recommended promotion workflow, see Version Sets & Promotion.

Dry-run by default. All mutating commands show what would change without --apply. Add --apply to execute.

Managing Version Sets (forge version-set)

List Version Sets

forge version-set list MyService -e production

# JSON output for scripting
forge version-set list MyService -e production --json

Shows all version sets for a service with their pinned versions and LLM preferences.

Create/Update a Version Set

# Create with unpinned versions (dev only)
forge version-set upsert personal-alex -s MyService -e dogfood --apply

# Create with pinned versions (resolves current latest)
forge version-set upsert personal-alex -s MyService -e dogfood --latest --apply

# Create by copying from another version set
forge version-set upsert preview -s MyService -e production --copy-from test --apply

# Pin specific versions
forge version-set upsert preview -s MyService -e production -a 5 -g 3 --apply

Version Existence Validation

When pinning to specific versions using -a (agent) or -g (context graph) flags, the CLI validates that those versions actually exist before applying the change.

$ forge version-set upsert preview -s MyService -e production -a 999 -g 888 --apply

Error: Agent version 999 does not exist. Use 'forge asset agent version-list' to see available versions.
Error: Context graph version 888 does not exist. Use 'forge asset context-graph version-list' to see available versions.

For advanced users who need to bypass this validation (for example, in automation scripts where versions may be created in parallel), use the --skip-version-check flag.

forge version-set upsert preview -s MyService -e production -a 5 -g 3 --skip-version-check --apply

Use --skip-version-check with caution. Pinning non-existent versions will cause runtime failures when the service is invoked.

Compare Version Sets

forge version-set diff preview release -s MyService -e production

# JSON output for scripting
forge version-set diff preview release -s MyService -e production --json

Shows a side-by-side comparison of two version sets, highlighting differences.

Promote Version Sets

# Promote to release (auto-backup creates release-previous for easy rollback)
forge version-set promote preview release -s MyService -e production --apply

# Skip auto-backup if needed
forge version-set promote preview release -s MyService -e production --no-backup --apply

Auto-backup. When you promote to release, a backup is automatically created as release-previous. Use --no-backup to skip this safety measure.

Rollback Version Sets

If a release causes issues, quickly revert to the previous configuration.

# Preview what would be rolled back (dry-run)
forge version-set rollback -s MyService -e production

# Execute the rollback
forge version-set rollback -s MyService -e production --apply

This is equivalent to forge version-set promote release-previous release, but makes the intent clearer and shows a comparison of the configurations.

Rollback 'release' to 'release-previous'
  Service: MyService (686d598b1234567890abcdef)
                         Configuration Comparison
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Field                 ┃ Previous (release-previous) ┃ Current (release) ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ agent_version         │ 27                          │ 28                │
│ context_graph_version │ 3                           │ 4                 │
│ llm_preferences       │ 2 configured                │ 2 configured      │
└───────────────────────┴─────────────────────────────┴───────────────────┘

Dry-run mode. Use --apply to execute.

The release-previous version set is created automatically when you promote to release. If you've never promoted to release, or used --no-backup, the rollback command will fail with an error.

Show Version Set Details

# Human-readable format
forge version-set show preview -s MyService -e production

# JSON output (for scripting)
forge version-set show preview -s MyService -e production --json

Delete a Version Set

forge version-set delete test-old -s MyService -e dogfood --apply

Cannot delete edge or release. Cannot delete version sets referenced by simulation unit tests.

Discovering Services (forge service)

Before working with version sets, you may need to discover what services exist and their current configuration. Use forge service commands to list and inspect services.

List Services

# List all services in an environment
forge service list -e production

# Filter by tag (e.g., production, phone, voice)
forge service list -e production --tag phone

# JSON output for scripting
forge service list -e production --json

Output shows services with their tags and version set counts:

Services in production
Filtered by tag: phone

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Name                      ┃ ID          ┃ Tags                ┃ Version Sets ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Customer Support          │ 686d598b... │ phone, voice        │            3 │
│ Sales Assistant           │ 68bb4c7f... │ phone, production   │            2 │
└───────────────────────────┴─────────────┴─────────────────────┴──────────────┘

Show Service Details

# Show full service configuration
forge service show "Customer Support" -e production

# JSON output for scripting
forge service show "Customer Support" -e production --json

Output includes linked assets and version set configuration:

Service: Customer Support
  ID: 686d598b1234567890abcdef
  Description: Voice support agent
  Active: Yes

Tags:
  - phone
  - voice

Linked Assets:
  Agent: support_agent (66e0d996f5a09fb3cf18ea73)
  Context Graph: support_context_graph (66e0d575f5a09fb3cf18ea5e)

Version Sets:
  Name       Agent Ver    CG Ver    LLM Config
  edge          latest    latest    defaults
  preview           28         4    2 set
  release           28         4    2 set

Related commands:
  forge version-set list Customer Support -e production
  forge asset agent version-list support_agent -e production

Check Service Health Status

Monitor the health of services across your organization to catch configuration issues.

# Check status of active services only (default behavior)
forge service status -e production

# Include inactive/disabled services in the analysis
forge service status -e production --include-inactive

# Focus on production-tagged services only
forge service status -e production --production

# Show only services with issues
forge service status -e production --issues

# Filter by tag
forge service status -e production --tag phone

# JSON output for monitoring/alerting
forge service status -e production --json

Detected Issues:

• Version set drift: preview and release configurations differ.
• Missing version sets: production services missing preview or release.
• Unpinned versions: production services with non-edge version sets using latest.

Example Output:

Service Status in production

Summary:
  Total services: 8  # Only showing active services by default
  Production services: 3
  Services with issues: 2
    - With preview/release drift: 2

Services Needing Attention:

Name           ID          Active  Prod   Preview  Release  Issues
MyService      507f1f7...  Yes     Yes    Yes      Yes      preview/release drift
OtherService   508f2a8...  Yes     Yes    No       Yes      missing preview

Discovery workflow: use forge service list to find services, forge service status to check health, and forge service show to inspect configuration before making changes with forge version-set commands.

Discovering Asset Versions (forge asset)

Before pinning specific versions in a version set, you need to know what versions exist. Use forge asset commands to discover agent and context graph versions.

List Agent Versions

# List versions for an agent by name
forge asset agent version-list MyAgent -e production

# List by agent ID
forge asset agent version-list 507f1f77bcf86cd799439011 -e production

# Show newest versions first
forge asset agent version-list MyAgent -e production --newest-first

# Get 50 most recent versions (pagination fetches multiple API pages automatically)
forge asset agent version-list MyAgent -e production --newest-first --limit 50

Output shows version numbers with creation timestamps:

Versions for Agent: MyAgent (507f1f77bcf86cd799439011)

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Version ┃ Created          ┃ Description ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│       1 │ 2024-04-11 23:52 │ -           │
│       2 │ 2025-01-30 19:38 │ -           │
│       3 │ 2025-01-30 19:51 │ -           │
└─────────┴──────────────────┴─────────────┘

Sorting and pagination. The --newest-first / -d flag sorts versions descending. When --limit exceeds the API's 10-per-page maximum, the CLI automatically paginates using continuation_token to fetch all requested results. Available on all version-list commands (agent, context-graph, behavior).

List Context Graph Versions

forge asset context-graph version-list MyGraph -e production

# Newest first with limit
forge asset context-graph version-list MyGraph -e production -d --limit 20

Output includes a state count for each version:

Versions for Context Graph: MyGraph (66997b4d40fe08f84ba0d1d1)

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Version ┃ Created          ┃ States ┃ Description          ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│       1 │ 2024-07-18 20:45 │     21 │ Initial version      │
│       2 │ 2024-08-07 17:06 │     22 │ Added new state      │
│       3 │ 2025-02-10 20:14 │     22 │ Bug fixes            │
└─────────┴──────────────────┴────────┴──────────────────────┘

Show Version Details

# Agent version details
forge asset agent version-show MyAgent 3 -e production

# Context graph version details (shows state breakdown)
forge asset context-graph version-show MyGraph 2 -e production

# JSON output for scripting
forge asset agent version-show MyAgent 3 -e production --json

Check Behavior Invocations

# See when/where a behavior was triggered
forge asset behavior invocations "Emergency Response Protocol" -e production

# JSON output for detailed analysis
forge asset behavior invocations "Emergency Response Protocol" -e production --json

Workflow: Pin Discovered Versions

# 1. Discover latest agent version
forge asset agent version-list MyAgent -e production

# 2. Discover latest context graph version
forge asset context-graph version-list MyGraph -e production

# 3. Pin specific versions in a version set
forge version-set upsert preview -s MyService -e production -a 3 -g 2 --apply

Tip: use forge version-set upsert --latest to automatically resolve and pin the current latest versions without looking them up manually.

Pre-Flight Validation

All mutating version-set commands (upsert, promote, delete) run pre-flight validation before applying changes. Configurations are validated before they reach the remote API.

Version-set-specific rules:

Rule	Scope	Behavior
Version existence check	All upsert commands	Error if a pinned agent or context graph version doesn't exist (bypass with --skip-version-check, see above)
Pinned versions required	Production services	Error if agent/context graph version is null
Cannot delete preview/release	Production services	Error blocks deletion
Preview required for release promotion	Production services	Error if preview doesn't exist

Channel and LLM rules (voice-optimized models, cost tiers, regional availability) are driven by the service's tags. See Channel Tagging: Validation for the full rules table.

Example: Blocked Mutation

$ forge version-set upsert preview -s "Voice Service" -e production --apply

Error: Version set 'preview' uses a non-voice-optimized LLM.
Voice preset 'voice' requires voice-optimized LLMs for low latency.
Use 'forge channel llm-info --channel phone' to see valid models.

Validation failed. Fix errors before proceeding.

Example: Warning (Non-blocking)

Warnings are displayed but don't block the operation.

$ forge version-set upsert test -s "Voice Service" -e dogfood --apply

Warning: Version set 'test' has empty llm_model_preferences. System defaults may
include non-voice-optimized LLMs. For voice preset 'voice', configure LLM preferences
explicitly using voice-optimized LLMs.

Create version set 'test'
  Service: Voice Service (66e0da39f5a09fb3cf18ea75)
  Agent version: latest
  Context Graph version: latest

Dry-run mode. Use --apply to execute.

Related Documentation

Version Sets & PromotionChannel Tagging System