> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/operations/devops/version-sets-best-practices/version-set-cli.md). # Version Set CLI Reference 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](/developer-guide/operations/devops/version-sets-best-practices.md). {% hint style="info" %} **Dry-run by default.** All mutating commands show what would change without `--apply`. Add `--apply` to execute. {% endhint %} ## Managing Version Sets (`forge version-set`) ### List Version Sets ```bash 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 ```bash # 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. ```bash $ 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. ```bash forge version-set upsert preview -s MyService -e production -a 5 -g 3 --skip-version-check --apply ``` {% hint style="warning" %} Use `--skip-version-check` with caution. Pinning non-existent versions will cause runtime failures when the service is invoked. {% endhint %} ### Compare Version Sets ```bash 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 ```bash # 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 ``` {% hint style="info" %} **Auto-backup.** When you promote to `release`, a backup is automatically created as `release-previous`. Use `--no-backup` to skip this safety measure. {% endhint %} ### Rollback Version Sets If a release causes issues, quickly revert to the previous configuration. ```bash # 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. ``` {% hint style="warning" %} 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. {% endhint %} ### Show Version Set Details ```bash # 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 ```bash forge version-set delete test-old -s MyService -e dogfood --apply ``` {% hint style="warning" %} Cannot delete `edge` or `release`. Cannot delete version sets referenced by simulation unit tests. {% endhint %} ## 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 ```bash # 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 ```bash # 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. ```bash # 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 ``` {% hint style="info" %} **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. {% endhint %} ## 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 ```bash # 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 │ - │ └─────────┴──────────────────┴─────────────┘ ``` {% hint style="info" %} **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). {% endhint %} ### List Context Graph Versions ```bash 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 ```bash # 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 ```bash # 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 ```bash # 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 ``` {% hint style="info" %} **Tip**: use `forge version-set upsert --latest` to automatically resolve and pin the current latest versions without looking them up manually. {% endhint %} ## 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](#version-existence-validation)) | | 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](/developer-guide/operations/devops/channel-tagging.md#validation) for the full rules table. ### Example: Blocked Mutation ```bash $ 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. ```bash $ 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 {% content-ref url="/pages/plGBeJQjrNSQTKi7tDnp" %} [Version Sets & Promotion](/developer-guide/operations/devops/version-sets-best-practices.md) {% endcontent-ref %} {% content-ref url="/pages/M5P6fUWwDoBjkvBKl2IT" %} [Channel Tagging System](/developer-guide/operations/devops/channel-tagging.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/operations/devops/version-sets-best-practices/version-set-cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.