galaxy/specs/REMOTE-1696/PRODUCT.md

Product Spec: Oz CLI Named-Agent CRUD

Summary

Add first-class Oz CLI commands for managing named agents. Developers can list, inspect, create, update, and delete named agents from the terminal with output modes that match existing Oz run commands.

Problem

Named agents are manageable through the public API and related Oz surfaces, but the Oz CLI does not expose the full CRUD surface. The existing oz agent list command lists repository-discovered agent skills, so the CLI needs a clear split between named agents and skills before adding CRUD commands.

Goals

• Make oz agent list mean "list named agents".
• Preserve skill discovery by renaming the existing command to oz agent skills.
• Provide terminal-friendly pretty output, script-friendly plain text, and JSON output with --jq filtering.
• Preserve server patch semantics for updates so users only pass fields they want to modify.
• Make list sorting predictable and client-side.

Non-goals

• Changing the public API behavior or authorization model for named agents.
• Adding interactive prompts for create or update.
• Managing API keys for named agents.
• Changing oz agent run or oz agent run-cloud semantics beyond continuing to accept an agent UID where already supported.

Behavior

1. oz agent skills lists available agent skills using the current oz agent list behavior, including the existing --repo option and repository authorization flow.
2. oz agent list lists named agents accessible to the authenticated user's team.
3. oz agent list supports --sort-by name and --sort-by created-at.
4. oz agent list supports --sort-order asc and --sort-order desc. If omitted, name sorting defaults to ascending, and timestamp sorting defaults to descending.
5. Sorting is performed client-side after the API response is fetched and before rendering pretty, text, or ndjson output.
6. oz agent get <uid> retrieves a single named agent by UID.
7. oz agent create creates a named agent. --name is required. Optional fields are accepted for the fields supported by the API: description, secrets, skills, base model, and default environment.
8. oz agent update <uid> partially updates a named agent. Users only pass fields they want to change.
9. oz agent update preserves omitted fields. Passing an empty value through an explicit remove flag clears fields where the API supports clearing.
10. oz agent update supports add/remove operations for list fields without requiring users to hand-write replacement arrays. Secrets use --add-secret <NAME>, --remove-secret <NAME>, and --remove-all-secrets; skills use --add-skill <SKILL>, --remove-skill <SKILL>, and --remove-all-skills.
11. oz agent delete <uid> deletes a named agent and reports success. If the server rejects deletion, such as for the default agent, the CLI surfaces the server error.
12. Pretty output for list uses a readable table with the core fields needed to identify and choose agents: UID, name, created time, description, secret names, skill specs, base model, and default environment when present. Disabled agents are hidden from pretty and text list output; when any are hidden, the CLI prints N disabled agents hidden to stderr after stdout output. JSON output still preserves the raw API response.
13. Pretty output for oz agent list also includes a hint for users looking for the old skill-discovery behavior: Looking for agent skills? Use <binary> agent skills instead.
14. Pretty output for get/create/update uses the same readable table shape for the single returned agent.
15. Plain-text output is stable and script-friendly tabular text with headers for both list and single-agent output.
16. JSON output for list/get/create/update preserves the API response shape so scripts can consume fields exactly as returned by the public API. List JSON is an object with an agents array.
17. Sort flags are rejected for JSON output, including --jq, so raw API output remains raw.
18. --jq implies JSON output even when the global output format is omitted or set to a human-readable format.
19. --jq filters list/get/create/update JSON output using the same jq behavior as oz run list and oz run get, including unquoted scalar output.
20. Delete has no JSON API response body. For JSON and ndjson output, the CLI emits a minimal operation result containing the deleted UID and deleted: true; pretty output reports the deleted UID in a sentence, text output prints the deleted UID, and delete does not support --jq.
21. All named-agent CRUD commands require authentication and reuse the existing CLI authentication and API-key behavior.
22. If the server returns authorization, validation, conflict, or not-found errors, the CLI prints the server-facing error through the existing fatal-error path.
23. The command hierarchy remains backward-compatible except for the intentional rename: users who want the previous skill list behavior must use oz agent skills.