feat(cli): promote profile to top-level command with list/describe/export/import

[zanetworker]

Problem

Provider profiles are buried under openshell provider list-profiles and openshell provider profile export/import. Two problems:

1. Inconsistent ergonomics. Most nouns in the CLI follow noun verb:

   openshell sandbox   list / create / get / delete
   openshell provider  list / create / get / delete
   openshell workspace list / create / get / delete
   openshell gateway   list / add / remove / select    ← inconsistent (add/remove vs create/delete)
   openshell policy    list / set / get / delete        ← inconsistent (set vs create)
   openshell service   list / expose / get / delete     ← inconsistent (expose vs create)
   

   Profiles break the pattern further: a hyphenated subcommand (list-profiles) nested under provider, and a further nested provider profile export/import. The verb inconsistencies across gateway, policy, and service are existing debt; profiles should not add to it.

2. No describe command. The only way to see what a profile contains (endpoints, credentials, binaries, auth style, default base URL) is:

   openshell provider list-profiles -o json | jq '.[] | select(.id == "openai")'

   There is no human-readable detail view for a single profile.

Proposed Design

Promote profile to a top-level noun with consistent subcommands:

openshell profile list                      # all profiles
openshell profile list --type provider      # filter by type (forward-compatible)
openshell profile describe <name>           # human-readable detail view
openshell profile export <name>             # export as YAML (existing functionality)
openshell profile import <file>             # import custom profile (existing functionality)
openshell profile update <file>             # update existing profile (existing functionality)
openshell profile delete <name>             # delete custom profile (existing functionality)
openshell profile lint <file>               # validate without registering (existing functionality)

profile list output

NAME             TYPE       CATEGORY         SOURCE
anthropic        provider   inference         built-in
openai           provider   inference         built-in
github           provider   source_control    built-in
nvidia           provider   inference         built-in
slack            provider   messaging         interceptor (signed)

The TYPE column is provider for all existing profiles. It is forward-compatible for future profile types without committing to what those types are.

profile describe output

openshell profile describe openai

openai (provider)
OpenAI-compatible inference

Default URL:   https://api.openai.com/v1
Credentials:   OPENAI_API_KEY (bearer)
Endpoints:     api.openai.com:443 (rest, enforce)
Binaries:      /usr/bin/curl

Source: built-in

openshell profile describe github

github (provider)
GitHub API and Git operations

Credentials:   GITHUB_TOKEN, GH_TOKEN (bearer)
Endpoints:
  api.github.com:443     (rest, read-only, enforce)
  api.github.com:443     (graphql, read-only, enforce)
  github.com:443         (rest, read-only, enforce)
Binaries:      /usr/bin/gh, /usr/local/bin/gh, /usr/bin/git, /usr/local/bin/git

Source: built-in

Structured output

openshell profile list -o json
openshell profile list -o yaml
openshell profile describe openai -o json

Same -o flag pattern as other commands.

Migration

• openshell provider list-profiles becomes an alias for openshell profile list --type provider
• openshell provider profile export/import/update/lint/delete becomes an alias for openshell profile export/import/update/lint/delete
• Old commands continue to work, no breaking change
• Docs and examples updated to use the new form

Scope

• CLI changes only, no gateway or proto changes
• Reuses existing ListProviderProfiles and GetProviderProfile gRPC RPCs
• describe formats the existing GetProviderProfile response for human reading
• --type filter is client-side on the existing profile data
• list/export/import/update/lint/delete wrap existing ProviderProfileCommands logic

Future consideration

The CLI has broader verb inconsistencies (add/remove vs create/delete, set vs create, expose vs create). A CLI-wide verb normalization pass could unify these, but that is a separate breaking change and should not block this issue.

Related

• Enhanced Provider Management #896 (Enhanced Provider Management)
• feat(cli): improve provider discoverability for agents and developers #2549 (improve provider discoverability)
• feat(providers): make Providers v2 the only provider system #1988 (make Providers v2 the only system)