ama-restish-cli - SKILL.md Agent Skill

name: ama-restish-cli description: Operate Any Managed Agents control-plane resources from a terminal using restish and the published OpenAPI document.

AMA restish CLI

Use this skill when an agent needs terminal automation for Any Managed Agents resources. This skill is documentation only: it does not define a bespoke AMA CLI binary or a replacement runtime protocol.

Setup

Set the deployment origin:

export AMA_ORIGIN="https://ama.example.com"

Authenticate through OIDC provider and provide a OIDC provider-issued OIDC access token. The current implemented OpenAPI security scheme is bearerAuth in /api/openapi.json.

Configure restish from the published OpenAPI document:

restish api configure ama "$AMA_ORIGIN/api/openapi.json"
restish ama get-health

Use JSON output when another tool will parse command output:
```
restish ama list-agents --rsh-output-format json
```

Workflow Map

Use OpenAPI operation names or documented /api paths. Do not invent local command names.

Resource	Read/list	Create/update	Archive/delete or command
Health	`getHealth`	n/a	n/a
Agents	`listAgents`, `readAgent`, `listAgentVersions`	`createAgent`, `updateAgent`	`archiveAgent`
Environments	`listEnvironments`, `readEnvironment`, `listEnvironmentVersions`	`createEnvironment`, `updateEnvironment`	`archiveEnvironment`
Sessions	`listSessions`, `readSession`, `readSessionReconnect`, `listSessionEvents`, `exportSessionEvents`, `streamSessionEvents`	`createSession`, `updateSession`	`stopSession`, `archiveSession`
Providers	`listProviders`, `readProvider`, `listProviderModels`	`createProvider`, `updateProvider`, `upsertProviderModel`	`deleteProvider`
Vaults	`listVaults`, `readVault`, `listVaultCredentials`, `readVaultCredential`, `listVaultCredentialVersions`	`createVault`, `updateVault`, `createVaultCredential`, `updateVaultCredential`, `rotateVaultCredential`	`archiveVault`, `deleteVaultCredentialVersion`
Governance	`readGovernancePolicy`, `readEffectiveGovernancePolicy`, `listProviderAccessRules`, `listBudgets`	`updateGovernancePolicy`, `createProviderAccessRule`, `createBudget`	`evaluateGovernancePolicy`
Usage	`listUsageRecords`, `readUsageSummary`	n/a	n/a
Audit	`listAuditRecords`, `exportAuditRecords`	n/a	n/a

Common Commands

restish ama list-environments --rsh-output-format json
printf '%s\n' '{"name":"Node workspace","packages":[{"name":"tsx","version":"latest"}]}' \
  | restish ama create-environment --rsh-output-format json

restish ama list-agents --rsh-output-format json
printf '%s\n' '{"name":"Research assistant","instructions":"Answer with citations."}' \
  | restish ama create-agent --rsh-output-format json

printf '%s\n' '{"agentId":"agent_abc123","environmentId":"env_abc123"}' \
  | restish ama create-session --rsh-output-format json
restish ama read-session sessionId:"session_abc123"
restish ama list-session-events sessionId:"session_abc123" --rsh-output-format json

restish ama list-providers --rsh-output-format json
restish ama list-vaults --rsh-output-format json
restish ama read-effective-governance-policy --rsh-output-format json
restish ama read-usage-summary --rsh-output-format json
restish ama list-audit-records --rsh-output-format json

Run pnpm run test:e2e in this repository when you need local evidence that the current OpenAPI document is ingestible by restish and that restish can serialize the core create environment, create agent, and create session workflow.

If SDK artifacts change, run pnpm run openapi:generate and pnpm run openapi:check. Restish remains the default command-line path; do not replace these workflows with a bespoke AMA CLI.

Safety Boundaries

Confirm ids before archiveAgent, archiveEnvironment, archiveVault, archiveSession, deleteProvider, or deleteVaultCredentialVersion.
Treat vault values and auth tokens as secrets. Never paste raw secret values into notes, commits, or screenshots.
Runtime interaction remains behind AMA session endpoints and canonical AMA events. Discover a session's runtimeEndpointPath with readSession, then use AMA runtime helpers for task traffic.
Do not add a bin, shell wrapper, package-manager global command, or project-specific command surface for AMA control-plane work.