SuperAPI AI Directory

soia-env-pi-cli-install

Coding & development

View repository

Updated 10-16 08:49

About this skill

soia-env-pi-cli-install

Install and verify Pi (@earendil-works/pi-coding-agent, command pi). It is a minimalist terminal coding assistant that runs an AI agent locally, managing credentials, execution history, and parallel collaboration for multiple AI CLIs. It is not Qwen/DeepCode or any other tool of the same name.

Customer-readable description

What this skill can do

What the customer wants What the skill will do What the customer can see
Install Pi Verify the project identity, Node.js, and npm, then install the upstream package Version, source, installation, and configuration directories
Check or update Compare versions from official npm metadata; after explicit authorization, update along pi update --self Update Updatable status or "updated"
Configure model/provider Check ~/.pi/agent/settings.json 's provider/model settings, protect credentials Configuration location and next steps for local secure configuration
Command unavailable Check PATH, the npm global directory, and commands of the same name Blocking causes and fixes

How the customer uses it

  1. The customer says "install Pi"; the Agent first confirms the target is @earendil-works/pi-coding-agent, and the customer does not need to operate a terminal.
  2. The Agent performs read-only checks of pi, Node.js, npm, the actual package source, and the version, then presents the plan.
  3. An installation request only authorizes installing a missing CLI; existing versions are not updated by default. An ambiguous "update" only shows the version; only an explicit "update to the latest" executes it.
  4. When running requires model credentials, the customer creates or manages the key themselves on the corresponding Provider platform (such as DeepSeek); the key must not be sent into the chat. The Agent only guides protected local input or uses the customer's existing secure credential injection.
  5. After completion, verify the version and help command; if credentials are not configured, truthfully write "installed, awaiting local configuration" instead of falsely reporting that it is running normally.

Initial configuration and real verification

  • ~/.pi/agent is only the default data directory (sessions, skills, extensions, git, npm packages); you must check both the directory and ~/.pi/agent/settings.json. The existence of the directory does not mean the provider is configured.
  • On first launch, pi initializes some local runtime state, but does not generate the settings.json。
  • Pi's model/provider configuration is in ~/.pi/agent/settings.json(such as defaultProvider、defaultModel、theme),does not contain the key; Provider credentials go through environment variables (such as DEEPSEEK_API_KEY) or pi auth。
  • After the customer creates an API key on the Provider platform, configure it in the shell environment (such as ~/.zshrc) or pi auth , and do not send the key to the Agent.
  • The Agent rechecks config_status、config_file_status, then performs side-effect-free verification; only if the actual request succeeds is the running status written as "normal".

Dependencies and installation

Dependency Type How to handle if missing
Node.js and npm Hard dependency Call soia-env-node-install to install a compatible stable version; do not force-install with an old Node
Network diagnostics Optional prerequisite Called when npm or GitHub is unreachable soia-env-network-diagnose
Provider credentials (such as DeepSeek API key) Runtime dependency Customer local security configuration, not sent to chat or logs
Other CLIs such as Qwen/DeepCode Non-dependency Same name but not the target of this skill, mixing installations is prohibited

For identity, package name, and configuration facts, see official-sources.md。

Standard process

  1. Execute python3 scripts/inspect_cli.py --json, read-only detection of pi, version, path, npm source,~/.pi/agent directory, and the actual existence status of settings.json .
  2. Read the actual node --version and npm global package source; if Node.js is below the required version, report the blocker first and do not run the installation package.
  3. Execute python3 scripts/check_latest.py --json, read the latest version of @earendil-works/pi-coding-agent from official npm metadata.
  4. If the command is provided by another package, write "Blocked: same-name command source mismatch" and do not overwrite. If the upstream package is installed and working normally, write "Installed" and do not update by default.
  5. When not installed, the Agent executes npm install -g @earendil-works/pi-coding-agent; if the npm global directory requires administrator privileges, first provide a user-level alternative and confirm, do not default to sudo。
  6. Only when explicitly updating to the latest, execute pi update --self(or npm install -g @earendil-works/pi-coding-agent@latest). Record the old version and npm prefix, do not switch to a Git repository development installation.
  7. Verify --version and --helpat the same absolute path. When the customer requests installation/configuration and the configuration is missing, the Agent prompts to configure provider credentials; when credentials are already securely configured, perform a side-effect-free verification; otherwise write "Unverified" for the running status.
  8. Recheck the version and directory, use scripts/render_status.py to output one line of customer status.

Credential configuration boundaries

  • ~/.pi/agent/settings.json Only stores non-secret configuration (provider/model/theme); the API key is not written to this file.
  • Prefer environment variables or local secure credential solutions such as pi auth ; if product capabilities force the use of a credential file, explain the risks first, restrict it to the user configuration directory, and set it to be readable only by the current user.
  • The customer does not provide keys in chat. The Agent does not read key contents, only verifies the result category of "whether it exists/whether it can authenticate".
  • In-project .pi/settings.json may enter Git; any key written to project configuration is always rejected.

Customer status list (mandatory)

The reply must begin with the following ten-column table, outputting only one row Pi:

Skill Current status Current version Latest version Running status Installation method Installation directory Configuration file directory Update time Processing result
Pi <Installed/Not installed/Blocked> <version or not obtained> <version or not obtained> <Normal/Abnormal/Unverified> <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 local configuration/Blocked: reason>
  • When the user asks only about Pi, do not add Node.js, npm, or other skill lines; Node.js is compressed in only when blocking 处理结果。
  • 更新时间 generated after final verification; directories use ~ relative paths to avoid usernames.
  • When already updated, 当前状态 still writes “installed”. When the source does not match, do not write “installed” based solely on the command name.
  • If the latest version cannot be obtained, write “not obtained”; do not guess.
  • config_status=未创建 or config_file_status=未创建 , the handling result must state “awaiting first-time configuration” and provide the Provider credential configuration entry point; do not report only a default directory.

Intermediate states of installation and update

Generate a random run_idduring actual installation or update, and at each actual stage immediately call scripts/record_install_progress.pyto synchronously display check, plan, awaiting confirmation, install/update, verification, and terminal state. Read-only checks do not create state.

Stage Current status Update time Handling result
<check/plan/awaiting confirmation/install or update/verification/complete or failed> <in progress/awaiting/completed/failed/blocked> <redacted result>

The update execution and verification stages must carry the customer's explicit latest-version authorization marker. Records save only fixed result codes and times, not npm output body, API key, account, full command text, or private paths.

Permissions and rollback

  • Prefer a user-level npm prefix; do not use sudoby default. Confirm first before modifying PATH/profile, overwriting a same-named command, or system-wide installation.
  • Before updating, record the old version and package identity; on failure, keep the old installation and do not automatically uninstall, downgrade, or delete configuration.
  • Installation must not rewrite the project package.json or lockfile.

Private information and intermediate data

  • Keep API keys in a customer-approved local secure location; SOIA configuration, audit state, and receipts do not store secrets.
  • Non-secret settings may remain in ~/.pi/agent/settings.json; project configuration stores only committable non-secret settings.
  • Machine change stage records are written to user-private state; version checks are stateless by default.
  • Do not record tokens, keys, accounts, prompts, code content, response bodies, or customer-private absolute paths.

Logs and completion receipt

The final receipt contains the fixed ten-column table, package identity, whether Node.js is satisfied, verification items, and whether the customer still needs to configure credentials on this machine. Normal dependencies are not expanded into extra lines.

Forward testing

Use a temporary fake pi to cover missing, normal, wrong package source, and version anomalies; mock the npm latest version; verify the Node.js gate, ten-column list, path redaction, no update by default, and the explicit 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-pi-cli-install -y

WorkBuddy 's loading unit is a role-based expert rather than a plugin,npx skills add -a '*' cannot cover it and it needs to be installed separately, see docs/install/workbuddy.md。