soha
soha provides native workbench commands and an AI Gateway entry point. It manages login and local profiles, with support for scripts, MCP stdio, and capability discovery.
Workbench commands use Soha APIs for registered resources. MCP tool calls pass through the Gateway to the owning application service. The server checks resource permissions, scopes, and audit requirements:
soha mcp
-> GET /api/v1/ai-gateway/capabilities
-> POST /api/v1/ai-gateway/tools/:toolName/invoke
-> POST /api/v1/ai-gateway/resources/read
-> POST /api/v1/ai-gateway/prompts/get
-> backend permissionKeys / scope grants / MCP tool grants / access policies / skill bindings / audit
-> owning application serviceInstallation, npx, and local builds
@opensoha/cli is a lightweight npm launcher for the native Go CLI, published and signed from Root opensoha/soha cli/v* releases (current verified version 0.2.1; cli/v0.2.0 published native archives and the container image only, without an npm package). It downloads the platform binary from the matching GitHub Release, verifies it against checksums.txt, and caches it by version. Use @latest interactively and pin an exact version in CI:
npx -y @opensoha/cli@latest mcp
npx -y @opensoha/cli@latest setup --client codex --mode both
npx -y @opensoha/cli@0.2.1 version --jsonYou can also download and verify platform archives directly from Root CLI releases or install the Go submodule with go install github.com/opensoha/soha/cli/cmd/soha@v0.2.1 (legacy v0.1.x standalone repository URLs and Go import paths may stop resolving once archived repositories are retired). setup writes the verified cached binary path into the MCP configuration, so starting the Agent does not download the binary again. Run the latest setup again to upgrade. For development, build the binary from the Root soha/cli source and add it to PATH:
cd ../soha/cli
go run ./cmd/soha help
go build -o ./bin/soha ./cmd/soha
mkdir -p ~/.local/bin
install -m 0755 ./bin/soha ~/.local/bin/soha
soha helpIf ~/.local/bin is not already in PATH, add it to your shell configuration:
export PATH="$HOME/.local/bin:$PATH"Current Gateway commands:
loginauth status|sessions|revoke-sessionwhoamilogoutprofile list|show|use|removecontext show|setcapabilitiestool callresource readprompt gettoken list|create|revoke|rotate|rotation-statusservice-account list|create|token-list|token-create|token-revoke|token-rotate|rotation-statusaudit listapproval list|timeline|approve|reject|cancelgovernance statusmcpmcp installsetupskill list|install|status|update|remove|rollbackdiagnosecompletion bash|zsh
skill install installs AI-readable workflows and methods only. It grants no additional permissions. Authorization still comes from the Gateway manifest, permission keys, scope grants, and MCP tool grants.
See AI Gateway Examples for end-to-end MCP client, CI service account, delivery/Kubernetes workflow, access policy, and skill binding examples.
Native Docker inventory (candidate versions)
The candidate CLI provides paginated, read-only discovery through existing Core APIs:
soha docker hosts list --search development --page 1 --page-size 20 --profile local
soha docker projects list --host-id host-1 --profile local
soha docker services list --host-id host-1 --project-id project-1 --profile local --output yamlEach command requests one page. Inspect data.total, data.page, and data.pageSize before requesting another page. Filters depend on the resource type; use the command’s help for supported options. The server applies the current role, Key permission ceiling, and configured resource scopes. A saved login does not grant additional workbench permissions.
Results contain a small inventory projection with configurationHidden: true. They omit configuration, environment values, Agent endpoints, and runtime container details. These lists do not implement conditional updates, full Docker CRUD, or container ownership verification. This section describes candidate behavior; it does not announce a release.
Native Docker terminal (candidate versions)
Matching candidate Core, Agent and CLI versions can open a real PTY in a registered service. Review its full 64-character container ID from service inventory first:
soha docker projects terminal project-1 --service api --expected-container-id FULL_CONTAINER_ID --yes --profile local
soha docker projects terminal-session project-1 --session-id UUID --profile local
soha docker projects terminal-close project-1 --session-id UUID --yes --profile localThe interactive command requires terminal stdin and stdout and rejects --output. The user or Key needs current docker.services.terminal permission; Key permission ceilings still apply. Governed AI Keys continue through Gateway/MCP. The session freezes the project, service, full container ID and original login session or Key. Another credential cannot resume it. An unsupported Agent returns an error without falling back to the legacy Compose terminal.
An administrator must also explicitly add docker.runtime.terminal.v1 to the matching Agent’s security.allowed_actions. The older docker.runtime.terminal action and bound-identity configuration do not enable this protocol. The default installer still pins an older Agent; use the matching candidate Agent and its explicit configuration for this feature.
The daemon adapter accepts Linux unix and tcp endpoints, with mTLS available for TCP. Live daemon acceptance covers Linux rootless Docker. Windows daemon and npipe endpoints are unsupported; Windows CLI console tests use a loopback protocol fixture and do not establish Windows daemon support.
The default lease is 300 seconds; --session-timeout-seconds accepts 1–900 seconds, capped by original credential expiry. Input is limited to 1 MiB and merged output to 32 MiB. The one-use connection ticket stays out of URLs, and the CLI never reconnects automatically. Ctrl-] detaches locally and requests closure. Disconnection, revocation or an unknown result does not prove remote process termination: query the original --session-id and verify remote effects. Success or failure requires the original container identity and an observed process exit code.
Native Kubernetes commands (candidate versions)
This section requires a candidate Core, Agent, and CLI combination containing the conditional resource APIs. It does not describe an available release. Check soha k8s --help locally first. An older server or Agent returns an error for unsupported conditional paths; the CLI retains the caller’s UID/version protection.
soha k8s clusters list --profile local
soha k8s namespaces list --cluster-id cluster-1 --profile local
soha k8s resources list Deployment --cluster-id cluster-1 --namespace default --profile local
soha k8s resources get Deployment api --cluster-id cluster-1 --namespace default --profile local
soha k8s events list --cluster-id cluster-1 --namespace default --limit 100 --profile local
soha k8s logs query --cluster-id cluster-1 --namespace default --pods api-1 --tail 100 --profile local
soha k8s logs tail --cluster-id cluster-1 --namespace default --pods api-1 --profile localresources currently supports 19 core kinds covering workloads, Pods, Nodes, configuration, network, storage, and namespaced RBAC. Check command help for the exact kinds. The server limits lists to authorized scopes. --all-namespaces applies only to lists; named operations use one namespace. Log queries are bounded, and tail polls for incremental results. Ctrl+C ends local following.
Read the identity and review the target before writing. Replace UID and RV below with that response’s uid and resourceVersion, retaining those values until a new review:
soha k8s resources identity Deployment api --cluster-id cluster-1 --namespace default --profile local
soha k8s resources apply Deployment api --cluster-id cluster-1 --namespace default --file reviewed.yaml --expected-uid UID --expected-resource-version RV --dry-run --profile local
soha k8s resources apply Deployment api --cluster-id cluster-1 --namespace default --file reviewed.yaml --expected-uid UID --expected-resource-version RV --profile local
soha k8s workloads scale Deployment api --cluster-id cluster-1 --namespace default --replicas 2 --expected-uid UID --expected-resource-version RV --dry-run --profile local
soha k8s rollout status Deployment api --cluster-id cluster-1 --namespace default --profile local
soha k8s rollout history Deployment api --cluster-id cluster-1 --namespace default --profile localApply, restart, scale, and rollback use real Kubernetes dry-run. Deployment supports restart/scale/rollback, StatefulSet supports restart/scale, and DaemonSet supports restart. Rollback requires an explicit --revision. A changed UID/version, external resource ownership, or field conflict blocks mutation. Review again before a new intent; the CLI does not replace the reviewed version automatically or force field ownership. A workload receipt confirms an API update; inspect rollout or resource details for actual readiness.
resources delete also requires an explicit UID/version. A deletion_requested receipt acknowledges the request and preserves finalizers. Read again to confirm that the object disappeared. --yes only skips CLI confirmation and does not change server permissions.
Creation uses preflight and a stable request Key:
soha k8s create preflight --cluster-id cluster-1 --file reviewed.yaml --profile local
soha k8s create execute --cluster-id cluster-1 --file reviewed.yaml --idempotency-key create-1 --profile localRetain the original file, Key, and operationId. After an unknown response, use the same file/Key with --retry-original. The server recovers an existing receipt first, or processes the first submission if the original request never arrived. Partial/failed batches still print the original receipt and return a nonzero exit code. Inspect completed items before deciding the next action.
Secret get/identity reads metadata by default. Secret YAML requires explicit --show-secret-data and separate server data permission. --output raw exports the authorized original content; protect exported files as sensitive data. Interactive TTY and TUI acceptance remain separate from the non-interactive argv path below.
Native commands serve authorized users and service accounts. Governed AI Keys use granted Gateway capabilities; the read-only k8s-sre remains read-only. --yes, client source fields, and Skill text do not grant write permissions. Switching to a broad profile must not bypass Gateway controls.
For governed Native scale goals, discover the candidate k8s.workloads.scale / k8s.workloads.scale.assess pair in the live manifest. The write requires independent approval and the original UID/version. Retain its original mutationRequestId, approved replicas and preconditions: verification requires a known applied receipt, the same credential and current permissions, and those desired replicas on the original UID. Later controller status revisions are allowed; rollout readiness and uninterrupted state are not assessed. The existing generic action and exact-revision assessment keep their original checks. Missing support does not authorize fallback or replay.
Pod argv execution and original receipts
The candidate CLI executes the exact arguments after --, with no implicit
shell. Use a reviewed Pod UID and a stable key for this one intent:
soha k8s resources identity Pod api-1 --cluster-id cluster-1 --namespace default --profile local
soha k8s pods exec api-1 --cluster-id cluster-1 --namespace default --expected-uid UID --container app --idempotency-key exec-1 --yes --profile local -- printf '%s\n' 'literal $(value)'
soha k8s pods execution api-1 --cluster-id cluster-1 --namespace default --idempotency-key exec-1 --profile local--exec-timeout-seconds defaults to 10 and is capped at 300. The combined retained
stdout/stderr budget defaults to 65,536 bytes and is capped at 1 MiB with
--max-output-bytes. --stdin-file FILE|- accepts at most 65,536 bytes; stdin
piping requires --yes. JSON/YAML preserve bounded process output and its encoding;
invalid UTF-8 uses base64. Text output escapes terminal control characters.
Known nonzero process exit codes from 1 through 255 become CLI exit codes; other
process codes remain in the structured receipt with a nonzero CLI result.
After a lost HTTP reply, query the original key or --execution-id. A repeated
original request returns its receipt; changing the target or input under the
same key conflicts. Running, timed-out, canceled, transport-lost and unknown
outcomes return a nonzero CLI status. Output and input are encrypted for seven
days, then removed; a minimal key tombstone prevents expired requests from
executing again. Audit records exclude command input and output.
Pod exec checks the UID before connecting and after normal completion. Kubernetes does not support an atomic UID precondition on exec; a changed target or uncertain result never authorizes automatic replay. Canceling a transport does not prove the remote process stopped. Current identity, original credential expiry, permission ceiling and resource scope remain enforced. Old Agents are unsupported without a legacy shell fallback.
Governed Pod execution through CLI tools and MCP
The matching candidate server exposes version 1 of k8s.pods.exec and
k8s.pods.exec.receipt. Use the dedicated k8s-pod-executor Skill and a credential
with Gateway invocation and Pod exec permission, scoped to the authorized
cluster, namespace and Pod. Capability discovery also requires Gateway view
permission. The read-only k8s-sre Skill does not include execution.
Save the reviewed request in pod-exec.json:
{
"clusterId": "cluster-1",
"namespace": "default",
"podName": "api-1",
"idempotencyKey": "pod-check-1",
"execution": {
"expectedUid": "REVIEWED_POD_UID",
"container": "app",
"argv": ["printf", "%s", "hello"],
"timeoutSeconds": 10,
"maxOutputBytes": 65536
}
}soha tool call k8s.pods.exec --profile ai-pod --capability-version 1 --input pod-exec.json --yes
soha approval approve APPROVAL_ID --profile local --comment reviewed
soha tool call k8s.pods.exec.receipt --profile ai-pod --capability-version 1 --input-json '{"clusterId":"cluster-1","namespace":"default","podName":"api-1","idempotencyKey":"pod-check-1"}'ai-pod represents the restricted credential; approval uses an authorized human
profile. --yes only confirms the submission. Execution requires independent
server approval even under an allow policy. MCP exposes the same tools, schemas,
approval and original receipt; a governed Key cannot use the native REST path
to bypass those controls. Both Direct and Agent connections are supported by
the matching candidate versions.
The receipt contains execution metadata. Separate outputState reports text,
redacted, binary_withheld or unavailable; Gateway text is redacted and
non-UTF-8 output is withheld rather than forwarded as base64. Original byte
counts describe the retained source bytes. Process success comes from the
receipt status and exit code. An unknown result does not authorize replay; query
the original key or execution ID. Approval views show input digests, not raw
argv or stdin. Matching candidate versions also support governed durable tasks
when protected persistence is explicitly enabled and the capability declares
original-call recovery and receipt verification. Missing prerequisites still
cause rejection. Recovery observes the original call and never replays an unknown
effect. k8s.pods.exec.assess proves only that the original process finished with
exit code zero, not business success or workload health. Interactive TTY remains
a separate native command.
Explicit interactive terminals and session queries
The candidate command requires terminal stdin and stdout; piping and JSON output cannot start it. Native TTY platform acceptance is recorded separately from argv acceptance. The candidate TUI is described below.
soha k8s pods terminal api-1 --cluster-id cluster-1 --namespace default --expected-uid UID --container app --profile local
soha k8s pods terminal-session api-1 --cluster-id cluster-1 --namespace default --session-id UUID --profile local
soha k8s pods terminal-close api-1 --cluster-id cluster-1 --namespace default --session-id UUID --yes --profile localThe default shell is /bin/sh; explicitly selecting /bin/bash requires that
program in the container. --session-timeout-seconds defaults to 300 and is capped
at 900 and the original access expiry. The lease freezes Pod UID, container and
shell under current exec permission, resource scope and Kubernetes RBAC. A
60-second ticket travels only in a dedicated header, is bound to the original
credential and can be consumed once. Agents without the versioned TTY protocol
are unsupported.
PTY stdout/stderr are merged and support resize. Aggregate input is limited to
1 MiB and output to 32 MiB; keystrokes and terminal output are not stored. Startup
prints the session UUID. Ctrl-] disconnects and requests closure, and the CLI
restores local terminal state on exit. Disconnection does not prove the remote
process stopped. Closure may first report closing; query the original session.
Only a verified final result yields a known process exit code. Disconnection or
unknown results return nonzero without reconnecting or starting another shell.
Metadata and the encrypted authorization snapshot are retained for 24 hours
after closure or expiry.
Native Delivery workbench commands (candidate versions)
These commands require the matching candidate CLI/Core/contracts combination. They operate through Soha HTTP APIs with the selected principal’s domain permissions and application/environment scope. --yes confirms the local request; server approval and generation checks still apply. Governed AI keys continue to use Gateway/MCP and cannot bypass that policy through a native command.
soha delivery applications list --search api --limit 20 --profile local
soha delivery applications detail app-1 --profile local
soha delivery applications runtime app-1 --profile local
soha delivery services list --application-id app-1 --profile local
soha delivery environments list --application-id app-1 --environment-id env-dev --profile local
soha delivery environment-catalog list --profile local
soha delivery blueprints usage blueprint-1 --profile local
soha delivery manifests revisions package-1 --profile local
soha delivery manifests bindings package-1 --profile local
soha delivery manifest-deployments list --application-id app-1 --profile localApplications, services and application environment bindings support create/update/delete. Pass typed JSON with --input FILE or --input -. Creation requires a stable id in the input; application/service updates require the reviewed expectedVersion, and environment updates require expectedUpdatedAt. A stale value produces a conflict. After an uncertain response, inspect the original ID before choosing another action: a stable resource ID is not a replayable idempotency key. Service commands always require --application-id.
soha delivery applications create --input application.json --yes --profile local
soha delivery services update service-1 --application-id app-1 --input reviewed-service.json --yes --profile local
soha delivery environments update binding-1 --input reviewed-environment.json --yes --profile local
soha delivery plans create --input reviewed-plan.json --yes --profile local
soha delivery plans get plan-1 --profile local
soha delivery plans confirm plan-1 --yes --profile local
soha delivery tasks get task-1 --profile local
soha delivery tasks logs task-1 --limit 200 --profile local
soha delivery tasks artifacts task-1 --profile local
soha delivery tasks wait task-1 --wait-timeout 10m --profile local
soha delivery tasks cancel task-1 --reason reviewed --yes --profile localA plan can remain waiting_approval, and a 202 task response can still be queued or failed. tasks wait succeeds only after the server reports completed; failure, cancellation, timeout and unknown status return nonzero. Detaching or pressing Ctrl+C does not cancel the durable task. Logs are a bounded persisted query (1–1000 rows), not a runtime stream. tasks cancel/retry require the action-scoped /control protocol; an old server without it is unsupported and receives no legacy fallback or redirected POST.
Manifest configuration reads include package pages, revisions, bindings and desired/observed deployments. Binding writes use manifest-bindings create/update/delete/set-revision; creation requires --package-id, updates require expectedVersion, and revision selection requires expectedGeneration. Reconcile/repair/adopt/rollback use the existing server policy and reviewed generation. Rollback input selects exactly one of targetRevision or useLastKnownGood. Native rollout controls require the reviewed uid and resourceVersion. These commands do not replace runner capability, deployment health verification or approval. For a binding creation with an uncertain response, inspect the original package’s bindings before another request.
Native AI workbench commands (candidate versions)
The candidate CLI reads ordinary chats, personal assistants, and runs as JSON or YAML through the public Copilot API. Ordinary chat does not implicitly enable a personal assistant or provision compute. Personal features remain subject to server approval, current permissions, and session ownership.
soha ai chat sessions list --profile local
soha ai chat sessions main --yes --profile local
soha ai chat sessions create --input chat.json --yes --profile local
soha ai chat sessions get SESSION_ID --profile local
soha ai chat messages window SESSION_ID --limit 40 --profile local
soha ai assistant access get --profile local
soha ai assistant access request --yes --profile local
soha ai assistant ensure --yes --profile local
soha ai assistant sessions list --profile local
soha ai assistant tasks list --profile local
soha ai assistant artifacts list --profile local
soha ai runs list --session-id SESSION_ID --profile local
soha ai runs events RUN_ID --after-sequence 0 --profile local
soha ai runs cancel RUN_ID --yes --profile local
soha ai runs resume RUN_ID --input resume.json --yes --profile local
soha ai chat native-request SESSION_ID --request-id original-turn-1 --profile localUse a public session input such as {"title":"Incident follow-up","mode":"general"} in chat.json, and {"input":"Additional user information"} in resume.json. Keep sensitive content in a file or --input -, rather than command arguments. Message-window cursors --around, --before, and --after are mutually exclusive; --limit is 3–100.
An access request does not approve itself. Explicit ensure creates or retrieves the approved user’s assistant identity and main session. HTTP 202 from cancel means accepted; read the actual run state afterward. The CLI does not report it as stopped. native-request only looks up the original session and requestId, without resending or resuming a message. A 404 does not prove an in-flight submission cannot commit later. The opaque requestId is preserved and bounded to 128 Unicode code points.
Native commands do not grant Gateway tool, Skill, budget, or approval permissions. Governed keys must use supported Gateway/MCP paths; a native denial never falls back to a broader profile. The candidate soha tui uses the same server permissions and durable receipts. JSON and streaming checks alone do not establish TUI or real-model acceptance.
Streaming submission and durable events
Review turn.json, for example {"content":"Check the current task status","requestId":"original-turn-1"}, before explicitly submitting:
soha ai chat messages stream SESSION_ID --input turn.json --yes --stream-timeout 10m --profile local
soha ai runs events RUN_ID --follow --session-id SESSION_ID --after-sequence 0 --wait-timeout 10m --profile localStreaming commands emit NDJSON only. Each source=submission line carries a POST SSE event. A final receipt.status=accepted acknowledges submission; Native and external queues have not thereby completed. An explicit terminal receipt ends this stream. Damaged HTTP/frames, empty EOF or wait expiry return nonzero with an unknown-outcome warning. Preserve the original session/requestId and inspect it; never automatically resend. POST redirects are refused. Only an explicit authentication rejection before handler execution allows one refresh and retry.
source=run-events is a separate durable channel. Save each page’s nextSequence and page while hasMore; never seed it from a submission connection’s sequence. Following also reads the original session’s authoritative run status. Completed exits successfully; failed/canceled/callback_timeout exit nonzero. Paused or waiting for input is not terminal. resyncRequired is printed before stopping: inspect the original run and explicitly choose a valid cursor, without automatically resetting or creating a replacement task.
Streaming defaults to a ten-minute wait, with a 2 MiB frame and 32 MiB total POST-response bound. An explicit global --timeout still limits each HTTP request. Ctrl+C or wait expiry detaches the viewer and does not cancel a durable task. To stop a task, explicitly use ai runs cancel RUN_ID --yes, then read its actual terminal state. Unsupported event APIs fail without a resend fallback.
Interactive workbenches (candidate versions)
soha tui --profile local --cluster-id cluster-1 --namespace defaultThe TUI requires a real terminal. Keys 1–6 select workbenches, Tab changes views, and Enter opens details. Writes first show a review and require explicit y; current server permissions, scope and approval still apply. While following events, q detaches the viewer without canceling the durable task. Use its explicit cancel action and inspect the original run to confirm termination. Capability discovery determines available actions; the TUI does not provision personal compute or bypass Gateway restrictions.
Directory synchronization and original requests (candidate versions)
Matching candidate CLI/Core versions provide organization preview, explicit synchronization and durable run queries. Preview does not write local directory projections. The server retains connector configuration and the people gate; the CLI does not export connector credentials.
soha directory sync preview --connection-id CONNECTION_ID --profile local
soha directory sync start --connection-id CONNECTION_ID --yes --profile local
soha directory sync request ORIGINAL_UUID --connection-id CONNECTION_ID --profile local
soha directory runs list --connection-id CONNECTION_ID --profile local
soha directory runs get RUN_ID --profile local
soha directory runs cancel RUN_ID --connection-id CONNECTION_ID --yes --profile local
soha directory runtime get --connection-id CONNECTION_ID --profile local
soha directory events list --connection-id CONNECTION_ID --limit 50 --profile localBefore sending, sync start prints a generated request UUID to stderr. Scripts may supply and retain a nonzero UUID with --idempotency-key UUID; use a fresh UUID for each new intent. Repeating the same UUID for its connection, original actor and credential only observes the original run, without another provider pull or projection. After a lost response, use sync request. Repeating the default start would generate a new UUID. Older Core versions without this protocol fail explicitly; the CLI does not fall back to legacy synchronization.
Preview and execution require access.directory.sync. Original-request lookup also requires access.directory.view and the original login session or Key. Current roles and the credential permission ceiling apply on every request. Canceling a running original request first returns cancelRequested: true; its state may remain running until execution stops. A later canceled state does not promise rollback of earlier committed changes. queued/running are not completion; failed/partial/canceled return a nonzero exit status. Preserve the UUID for diagnosis without automatic replay. Run lists remain capped at 50; the event list’s --limit does not change that cap.
Network operations and same-session MFA (candidate versions)
These commands require matching candidate Core/CLI versions and do not announce a release. Before issuing an access grant that requires MFA, verify an existing factor in the same login session. Another profile, session, or key does not inherit that session’s MFA.
soha auth mfa status --profile local
soha auth mfa totp --profile local
soha auth mfa verify --challenge-id CHALLENGE_UUID --response-stdin --profile localFor an existing factor, totp starts step-up verification. Initial enrollment exposes an authenticator URI only with explicit --show-enrollment; view it in a private terminal. verify hides input on a real terminal and also accepts bounded stdin. Codes are never positional arguments. Verification does not expand domain permissions, and a key cannot borrow a user’s session MFA.
soha network-access sessions plan SESSION_ID --input action.json --profile local
soha network-access sessions execute SESSION_ID --input reviewed-command.json --yes --profile local
soha network-access sessions command COMMAND_ID --session-id SESSION_ID --profile local
soha network-access sessions request ORIGINAL_PLAN_HASH --session-id SESSION_ID --profile localKeep the server plan’s planHash in the reviewed execution input. The CLI prints the original hash to stderr before submission. After an unknown response, query that hash or original command ID before another action. pending/delivered does not prove NAS execution. Reads recheck current permission and the parent session; unsupported older servers fail explicitly.
Alert healing and original workflows (candidate versions)
soha observe events heal EVENT_ID --policy-id POLICY_ID --idempotency-key ORIGINAL_UUID --yes --profile local
soha observe healing-runs request ORIGINAL_UUID --event-id EVENT_ID --profile local
soha observe healing-runs get HEALING_RUN_ID --profile local
soha observe healing-runs approve HEALING_RUN_ID --input-json '{"comment":"Reviewed"}' --yes --profile local
soha observe healing-runs retry HEALING_RUN_ID --yes --profile localheal prints the original UUID and creates a pending approval run. Recover an unknown response with the same actor and original login session or key; there is no legacy /heal fallback. Deleting a run never frees its UUID for recreation. When policy requires on-call approval, approval and rejection use the current on-call configuration; historical candidates cannot authorize a decision.
Approval persists a stable workflow ID and an unknown dispatch fence before invoking the existing executor. Duplicate approval only observes that workflow. Running or unknown outcomes cannot be retried or overwritten by rejection. Explicit retry accepts a rejected run or a known failed original workflow and opens a new pending approval generation. Earlier steps may have partial effects, so inspect them first. completed is the actual workflow state; verify the business goal against its resources. This protocol does not promise automatic completion after arbitrary process interruption.
Login
CLI v2 authentication is being prepared for release. The device, credential-store and rotation-recovery behavior below requires a matching Core/Web/CLI combination. Enable
auth.cli.enabledonly after compatibility verification. Older instances require explicit--method legacy-password; the new CLI never silently falls back to passwords.
Browser device authorization is the default, so third-party users do not need a local password:
soha login --server http://127.0.0.1:8080 --profile local
# Remote terminals or manual browser opening
soha login --server https://soha.example.com --profile local --device-code --no-browserOpen the complete URL printed by the terminal, sign in to the same Soha instance, and enter its six-digit code, including leading zeroes. Review the account, instance, terminal, permissions and expiry before explicitly approving or denying. A six-digit code alone cannot locate arbitrary requests. The request locator is a high-entropy, unguessable handle in the URL fragment; Web removes it before third-party login and retains it briefly in the current tab. Do not forward login links or approve requests initiated by someone else.
Accounts with MFA must verify an existing authenticator, Passkey or recovery code. Enrolling a new factor cannot replace verification with an existing factor. Requests expire after five minutes by default. Ctrl+C attempts cancellation. After a lost response, repeating login for the same server/profile resumes the original request. Use --restart to abandon it and review CLI sessions in your profile.
Local passwords remain an explicit compatibility path, subject to account and instance policy:
soha login --server http://127.0.0.1:8080 --profile local --method password --login admin
# Supply a password on stdin rather than in arguments or shell history
soha login --server http://127.0.0.1:8080 --profile local --method password --login admin --password-stdinInstances requiring additional verification direct users to browser device login. SSO/MFA is not bypassed. Use --method legacy-password for the original endpoint on an older instance.
Key import accepts personal access tokens (PATs) and service-account tokens:
# Feed a Key from a secret manager or controlled stdin; never put it in arguments
soha login --server https://soha.example.com --profile local --with-token
soha whoami --profile local --jsonImport validates the identity and stores the original Key without creating a refreshable user session. PATs retain their selected permissions; service-account tokens retain their service identity. An LLM Key does not automatically gain platform permissions. CI can inject SOHA_SERVER and SOHA_TOKEN for stateless authentication without a profile. Environment tokens are never refreshed or persisted. Logging out or removing a profile does not unset environment variables.
Credential storage and isolation
Configuration defaults to ~/.soha/config.json; isolate it with SOHA_CONFIG=/abs/private/config.json. New configuration stores references and metadata. The separate token envelope is bound to the server, deployment path and profile. Parent directories use 0700, files use 0600, and Windows uses a private ACL for the current user.
New login defaults to --credential-store auto, using the system credential store. Failure is explicit and never silently falls back. For a headless environment, choose --credential-store file; its private credential files contain plaintext secrets and must be protected accordingly. ephemeral only verifies credentials: it revokes a newly created password/device session before normal exit and leaves an imported shared Key active. It preserves existing profiles and returns verified: true, authenticated: false, persisted: false in JSON; session validation also returns temporarySessionRevoked: true. A failed revocation returns ephemeral_cleanup_unconfirmed and requires reviewing the session in Web. Use environment Key authentication for subsequent stateless commands. A legacy plaintext v1 profile migrates into a separate file envelope after its first successful refresh, retaining its existing storage choice. Sign in again to select the system credential store.
Concurrent refreshes of one profile use process locks and durable request IDs. New v2 CLI sessions default to fifteen-minute access, seven-day idle and thirty-day absolute expiry. Natural access expiry can refresh; revoked sessions, disabled accounts or absolute expiry require a new login. Existing Web/App/CLI refresh semantics remain compatible.
When rolling back to an older CLI, keep the new CLI available to recover or revoke v2 sessions, or revoke them in Web. An older CLI cannot read v2 credentials and may overwrite configuration fields it does not recognize. Run it with a new, separate SOHA_CONFIG path and sign in again; never point it at your migrated configuration or copy token values between files.
Identity, logout and revocation
soha auth status --profile local --json
soha auth status --profile local --offline --json
soha whoami --profile local --json
soha auth sessions --profile local
soha auth revoke-session --profile local --id SESSION_ID
soha logout --profile local
soha logout --profile local --local-only
soha profile remove localOnline status and whoami query the server. Offline status describes local metadata and does not prove authentication. Default logout revokes a CLI user session before clearing its local reference; temporary server failure preserves recovery credentials. --local-only clears local authentication only. Key logout also removes only the local copy by default; explicit --revoke affects every client sharing the Key. profile remove deletes only local configuration. The profile’s CLI sessions tab can revoke a terminal session from Web.
profile show displays metadata only. Never place credential files, full tokens, kubeconfigs or environment variables in logs, issues, AI conversations or diagnostic attachments.
Profiles and context
soha profile list
soha profile show local
soha profile use localAI client context is sent to the Gateway as request headers for auditing and tool-grant filtering:
soha context set \
--profile local \
--ai-client-id codex-local \
--ai-client Codex \
--skill-id delivery-developer \
--source sohaThe corresponding headers are:
X-Soha-AI-Client-IDX-Soha-AI-ClientX-Soha-Skill-IDX-Soha-Source
Capability inspection
soha capabilities --profile local
soha capabilities --profile local --json
soha capabilities --profile local --output names
soha capabilities --profile local --output inputs
soha capabilities --profile local --domain platform --output names
soha capabilities --profile local --domain platform --output jsoncapabilities calls GET /api/v1/ai-gateway/capabilities and prints the tools, resources, prompts, skills, permission keys, and manifest summary available to the current identity. --output inputs summarizes required fields and properties from each tool’s manifest inputSchema and outputSchema.
--domain platform calls GET /api/v1/clusters/capabilities instead and prints the runtime capability matrix for Direct and Agent connection modes. It reports YAML apply/delete, CRD, Helm, logs, exec, port-forward, Docker runtime, and related capabilities as available, partial, or unsupported. Platform capabilities support json, yaml, and names; inputs applies only to the default Gateway manifest.
If a capability is missing, check:
- The active profile points to the intended server.
- The user or token has
ai.gateway.view. - The business tool’s domain permissions, such as
delivery.*, are granted. mcp_tool_grantshas not narrowed the tool set.ai_access_policiesorai_gateway_skill_bindingshas not narrowed the current AI client, role, or subject.
Tool calls
Call a Gateway tool manually as a fallback:
soha tool call k8s.pods.list \
--profile local \
--input ./pod-list-input.json--input - reads JSON from standard input. You can also use --input-json '{"clusterId":"cluster-a","namespace":"prod"}'. The CLI calls only POST /api/v1/ai-gateway/tools/:toolName/invoke; it does not access the database, Kubernetes, or runners directly.
Resources and prompts
Read a Gateway MCP resource or prompt when diagnosing the context visible to an MCP client:
soha resource read soha://delivery/applications \
--profile local \
--context-json '{"applicationId":"app-1"}'
soha prompt get soha.delivery.plan_release \
--profile local \
--arguments-json '{"applicationId":"app-1"}' \
--context-json '{"environmentId":"dev"}'resource read calls only POST /api/v1/ai-gateway/resources/read; prompt get calls only POST /api/v1/ai-gateway/prompts/get. --context - and --arguments - read JSON from standard input, but only one argument source may use standard input in a single command. Output follows the CLI redaction rules.
Tokens and service accounts
Personal tokens:
soha token list --profile local
soha token create --profile local --name codex-local --permission-keys ai.gateway.view,ai.gateway.invoke
soha token revoke --profile local pat-123Service accounts:
soha service-account list --profile local
soha service-account create --profile local --name ci-runner --role-ids delivery-operator
soha service-account token-list --profile local
soha service-account token-create --profile local --service-account-id sa-123 --name ci-token
soha service-account token-revoke --profile local sat-123The backend returns a newly created plaintext token once. token-list returns only the token ID, owning service account, prefix, permissions, scopes, expiry, last-used time, and revocation state. List, audit, and diagnostic output is redacted by default and does not expose token hashes, kubeconfigs, environment variables, or secret-like fields.
Key expiry and rotation recovery
New Keys created or rotated by the new CLI or Web default to ninety days, with an explicit future expiry also supported. Legacy API omission semantics remain unchanged; existing unlimited Keys are not rewritten.
soha token rotate --profile local --id PAT_ID --auth-profile manager
soha token rotation-status --profile local --request-id REQUEST_UUID --auth-profile manager
soha service-account token-rotate --profile local --id SAT_ID --auth-profile manager
soha service-account rotation-status --profile local --request-id REQUEST_UUID --auth-profile managerSuccessful rotation immediately revokes the old Key. For a shared Key, create a replacement, update and verify every client, then revoke the old Key to arrange a smooth transition. Rotation requires a different valid session or management Key. --auth-profile must use the same instance and ignores ambient SOHA_TOKEN.
Before sending, the CLI saves a non-secret request ID and prints it to stderr. Query that original ID after a lost response. The server creates the replacement, revokes the old Key and records the outcome in one transaction. Recovery returns only the replacement ID and completion status, never the new plaintext again. If it was not saved, revoke the replacement and create another Key. Web also retains a rotation recovery record in the current tab. Do not generate another request ID to guess whether the previous rotation completed.
Audit
Query Gateway audit records:
soha audit list --profile local --tool-name diagnosis.release_failure.analyze --limit 20
soha audit list --profile local --actor user-1 --from 2026-05-29T00:00:00ZFilters include actor, actor type, AI client, skill, tool, risk level, result, action, from/to, and limit. Times use RFC3339.
Governance
Inspect Gateway governance health and operational metrics:
soha governance status --profile local
soha governance status --profile local --window-hours 48 --jsongovernance status calls GET /api/v1/ai-gateway/governance/status. It uses the last 24 hours of audit records by default; explicit --window-hours values are limited to 1 through 168. Output covers health checks, successful/denied/failed calls, pending approvals, approval SLA, PAT and service-token usage, AI client registration status, budget/rate-limit/redaction/resource-scope coverage, and anomalous findings. Text output is redacted and includes structured recommendation actions. --json preserves the complete redacted DTO. Configured rate limits, budgets, redaction policies, and resource scopes are enforced by the backend before invocation; the CLI only displays the governance summary.
Approval requests
Use the CLI to inspect and decide approval requests found in governance output or the Console:
soha approval list --profile local --status pending --tool-name delivery.actions.trigger
soha approval timeline approval-123 --profile local
soha approval approve approval-123 --profile local --comment "approved in change window"
soha approval reject approval-123 --profile local --comment "missing rollback plan"
soha approval cancel approval-123 --profile local --comment "duplicate request"approval list proxies GET /api/v1/ai-gateway/approval-requests and supports ID, status, actor, actor type, AI client, skill, tool, risk level, strategy, time, and limit filters. approval timeline proxies GET /api/v1/ai-gateway/approval-requests/:requestID/timeline. Approval commands proxy the existing approval APIs; candidate approvers, change windows, multi-stage quorum, AI client activation, and tool replay remain backend responsibilities. CLI output redacts tool input, decision comments, execution output, and related metadata.
MCP stdio server and Agent configuration
Start the local server:
soha mcp --profile local
soha mcp --profile local --base-url https://soha.internal.exampleThe official hosted endpoint https://mcp.opensoha.com is the default. Self-hosted deployments must pass --base-url explicitly. Configure an Agent’s MCP and Skills together with:
soha setup --client codex --mode both --profile local
soha setup --client codex --scope project --mode both --profile local
soha setup --client claude --mode mcp --base-url https://soha.internal.example
soha setup --client codex --checkThe default --scope user writes user-level configuration. --scope project writes repository-local client configuration, the Agent skill, and the .soha/skills runtime. Explicit --config, --dest, and --runtime-skill-dest values override the scope. Supported clients are codex, claude, cursor, kiro, gemini, antigravity, antigravity-ide, and trae.
To print generic MCP JSON manually, use:
soha mcp install --profile local --command /usr/local/bin/sohaThe generated command arguments use the direct mcp entry point:
{
"mcpServers": {
"soha": {
"command": "/usr/local/bin/soha",
"args": ["mcp", "--profile", "local"]
}
}
}Without --profile, mcp install uses the current profile. --ai-client-id, --ai-client, and --skill-id are written into the generated mcp arguments to pin the audit source, AI client context, and skill binding. mcp start remains a compatibility form.
The MCP server supports:
initializetools/listtools/callresources/listresources/readprompts/listprompts/get
The local process is an AI Gateway proxy. It does not directly access PostgreSQL, Kubernetes, Docker, runner workspaces, or the local kubeconfig, and it cannot bypass backend permissions. Tool, resource, and prompt lists are generated dynamically from the Gateway manifest. Schemas and _meta.soha metadata describe inputs, outputs, permission keys, scopes, adapters, risk, and approval requirements. Tool calls, resource reads, and prompt requests are always proxied through the corresponding backend endpoints.
Resources use manifest URIs such as soha://delivery/applications, soha://delivery/execution-tasks, and soha://k8s/runtime. Prompts include soha.delivery.plan_release and soha.k8s.diagnose_workload. Skill bindings can further narrow the resources and prompts visible to a client.
Skills
The initial built-in Skills are:
delivery-developerdelivery-testerk8s-sresecurity-change
List Skills from the latest stable GitHub Release:
soha skill listInstall one Skill:
soha skill install \
--dest ~/.soha/skills \
delivery-developerInstall all Skills:
soha skill install --allThe default source is the latest stable skills/v* GitHub Release in opensoha/soha, never a branch. Pin a release for reproducible installs or rollback with --source github:opensoha/soha@skills/v0.1.4. Existing pins such as github:opensoha/soha-skills@v0.1.0 remain supported for historical recovery while their old repository URLs resolve. Local checkouts, release tarballs, and HTTPS release URLs remain supported through --source. The default destination is ~/.soha/skills; --scope project uses .soha/skills in the current repository, while explicit --dest or SOHA_SKILLS_DIR values override the default.
Install and update stage a complete generation before activation. The previous verified generation remains available for rollback, and operations append to the local JSONL installation audit:
soha skill status
soha skill update
soha skill remove k8s-sre
soha skill rollbackSkills describe workflows; they are not a security boundary. An AI client must still use MCP tools visible to its current identity.
Diagnostics
soha diagnose --profile local
soha diagnose --profile local --tool k8s.pods.logs
soha diagnose --profile local --resource soha://k8s/runtime
soha diagnose --profile local --prompt soha.k8s.diagnose_workload
soha diagnose --profile local --cluster-capability resource.yaml.apply
soha diagnose --profile local --tool k8s.pods.logs --ai-client-id codex-local --skill-id k8s-sre --source codex-mcpdiagnose validates the profile, server, token, and Gateway capability path, then prints tool/resource/prompt/skill/permission-key counts. Tool diagnostics include risk, approval requirements, permission keys, scopes, and summarized input/output schemas. Resource and prompt diagnostics identify the relevant permissions and binding context. AI client flags override only the current diagnostic request and do not modify the profile. Tokens are never printed.
--cluster-capability reads the platform capability matrix and explains the selected capability’s Direct/Agent support, required scopes, risk, approval requirement, and documentation URL.
Completion
soha completion bash
soha completion zsh