soia-env-opencode-cli-install

Install and verify the OpenCode CLI (command opencode). The Agent handles terminal operations; the customer only completes login or authorization on the official page of the chosen model provider.

Customer-readable instructions

What this skill can do

What the customer wants	What the skill will do	What the customer can see
Install OpenCode	Check existing sources and install via the official stable channel	Version, source, install and configuration directories
Check or update	Compare with the latest official GitHub release; upgrade along the original source only after explicit authorization	Updatable status or “updated”
Configure model provider	Handle only non-secret settings and launch official authentication	Configuration location and browser next steps
Command unavailable	Check PATH, duplicate copies, and configuration overrides	Blocking cause and fix

How the customer uses it

Other recognizable phrasings include “opencode does not exist” and “update OpenCode to the latest.”

The customer says “install OpenCode”; do not ask the customer to copy terminal commands.
The Agent first performs a read-only check and shows the plan; installing a missing CLI does not authorize updating an existing CLI.
An ambiguous “update OpenCode” only shows the current and latest versions; only an explicit “update to the latest” performs the upgrade.
Do not ask for an API key during configuration or login; if there is an official OAuth/browser flow, the customer completes it on the official page.
After completion, verify the version, help command, and side-effect-free startup, then output a single fixed status line.

First-time configuration and real authentication verification

~/.config/opencode is a configuration candidate directory; provider credentials are usually written by opencode auth login to ~/.local/share/opencode/auth.json, and the two must be checked separately; do not treat a nonexistent directory as configured.
For first-time configuration, the Agent launches opencode auth login; the customer completes OAuth on the provider’s official page or enters credentials in the official interactive interface; the Agent does not receive or echo API keys.
After completion, run opencode auth list, then launch OpenCode and perform a side-effect-free model/help check; when there are no provider credentials, write “waiting for provider login/configuration” in the result.
Only create ~/.config/opencode/opencode.json or project opencode.jsonwhen custom models or project settings are needed; a nonexistent default configuration file does not mean the CLI installation failed.

Dependencies and installation

Dependency	Type	How to handle if missing
Officially supported operating systems	Hard dependency	If unsupported, stop and explain
Node.js/npm	npm channel dependency	Standalone installation and Homebrew do not need it; only the npm channel calls `soia-env-node-install`
Network diagnostics	Optional prerequisite	Called when the official site or provider login fails `soia-env-network-diagnose`
Model provider account	Runtime dependency	The customer chooses a provider and authorizes in the official interface; secrets are not read

Official sources are listed at official-sources.md。

Standard procedure

Execute python3 scripts/inspect_cli.py --json, read-only detection of opencode, version, source, installation directory, configuration override path, and the actual existence status of the configuration file.
Execute python3 scripts/check_latest.py --json, obtain the latest version from the anomalyco/opencode official GitHub latest release.
When installed and normal, write "installed"; if there is no explicit authorization for the latest version, stop and do not perform startup updates or the installer.
When not installed, prefer the official standalone channel; when the customer chooses npm, use npm install -g opencode-ai, and when choosing Homebrew, use the official tap. For network scripts, first download to a separate temporary directory and inspect, then execute the local copy; do not directly execute network responses.
After explicitly updating to the latest, prefer using the current absolute path to execute opencode upgrade and keep the source; npm/Homebrew sources may also be updated along the detected package manager. Do not silently switch sources.
Verify the same command's --version、--help and side-effect-free startup. When model login is required, start the OpenCode official authentication process and hand the browser over to the customer.
Re-detect the version, directory, and configuration, and use scripts/render_status.py to output the customer list.

Product auto-update boundaries

OpenCode may check for and download updates at startup; this skill does not call the updater by default, but it must disclose the product's autoupdate behavior.
Read-only checks must not change autoupdate to false、notify or any other value.
When the customer requests changing the auto-update setting, first show the impact and confirm separately; a configuration change does not equal authorization for this upgrade.

Customer status list (mandatory)

The reply must begin with the following ten-column table, outputting only one row OpenCode CLI：

Skill	Current status	Current version	Latest version	Running status	Installation method	Installation directory	Configuration file directory	Update time	Handling result
OpenCode CLI	<installed/not installed/blocked>	<version or not obtained>	<version or not obtained>	<normal/abnormal/unverified>	<official standalone installation/Homebrew installation/npm global installation/not obtained>	<directory or not obtained>	<directory or not obtained>		<installed/already latest/updatable, not executed/waiting to confirm whether to update to latest/updated/waiting for login/blocked: reason>

When the user only asks about OpenCode CLI, do not add Node.js, npm, model provider, or other skill rows.
更新时间 is the final verification time; for directories use ~ relative paths to avoid usernames.
If updated, still write "installed"; for multiple copies, report only the one effective in the login shell and indicate the conflict, without automatically deleting.
If obtaining the latest version fails, write "not obtained"; do not guess.
config_status=未创建 and when credential status is not found, write "waiting for provider login/configuration" in the handling result; if there is only a credential file and no opencode.json, it must be explained that this is the normal authentication storage location, and the customer must not be asked to recreate the configuration file.

Intermediate states of installation and update

When actually installing or updating, generate a random run_id, and at each actual stage immediately call scripts/record_install_progress.py, synchronously display check, plan, wait for confirmation, install/update, verify, and final states. Read-only checks do not create state.

Stage	Current Status	Update Time	Processing Result
<check/plan/wait for confirmation/install or update/verify/completed or failed>	<in progress/waiting/completed/failed/blocked>		<redacted result>

Updated execution and verification stages must carry an explicit customer authorization marker for the latest version. Events only store fixed result codes and times, not full command text, vendor responses, tokens, account names, or private paths.

Permissions and Rollback

Prefer user-level installation; do not use sudoby default. Confirm first before modifying PATH, overwriting configuration, switching installation sources, or performing system-wide installation.
Before updating, record the old version and source; on failure, keep the original installation and do not automatically uninstall, downgrade, or reset configuration.
Installation scripts exist only in the system temporary directory and are cleaned up on success, failure, or cancellation.

Private Information and Intermediate Data

Credentials are managed by the vendor's official OAuth/login state, OpenCode's official credential storage, or the system credential store; they are not read or echoed.
Non-secret configuration remains in ~/.config/opencode or the customer-specified override path; SOIA does not copy secrets.
Machine-change stage records are written to user-private state; version checks are stateless by default.
Do not record API keys, tokens, cookies, authorization codes, account names, response bodies, or customer-private absolute paths.

Logs and Completion Receipt

The final receipt includes the fixed ten-column table, verification items, whether automatic update settings are read-only, and whether the customer still needs browser login. Normal dependencies are not expanded into extra rows.

Forward Testing

Use a temporary fake opencode to cover missing, normal, abnormal, and multiple copies; mock the GitHub release; verify ten-column rendering, configuration override, path redaction, no update by default, and the update authorization gate.

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-env@soia

Install only this one skill:

npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-opencode-cli-install -y

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it and requires separate installation, see docs/install/workbuddy.md。