CLI troubleshooting

Help your coding agent recover sign-in, funding, configuration, and verification problems during RunInfra setup.

Ask your agent to run runinfra doctor --json first. It changes nothing and sends no paid check.

If you see

What you see	Do this
No eligible workspace or Not available for this role	A workspace owner must approve.
The wrong workspace	Switch workspaces in RunInfra and reload the approval page.
The code expired	Ask your agent for a new code.
Your agent cannot run commands	Leave plan or read-only mode. In Codex, approve running outside its sandbox.
Your agent asks for a key	Do not paste it. Point your agent to the setup instructions.
Browser sign-in is unavailable	Use manual setup. Keep keys out of the chat.
Add credits in Billing before connecting.	Add credits in Billing before approving a connection.
The new command is not found	Step-by-step setup adds the folder to PATH; open a new terminal. If needed, run the full path your agent gave or add ~/.config/runinfra/bin to PATH (%LOCALAPPDATA%\runinfra\bin on Windows).
Inside is refused from a separate command’s terminal	Open a normal terminal outside claude-run or codex-run and try again.
You still see the old model	Start the new command, pick a RunInfra model, or fully restart as instructed. A paid check does not change your current chat.
Goose or Zed has no key	Load the environment file your agent names and restart the app from that same terminal. Follow Goose or Zed.
One project uses another model	Check that project’s settings, environment files and launch flags.
The paid check failed after saving	Fix the reported billing or network problem, then ask for Doctor. Approve a fresh plan before another attempt.
This key's payer is set by the workspace owner.	Ask the workspace owner.
The name is taken	Choose another name with --name.

Codes your agent reports

Code	Next step
usage	Read the message and runinfra help --json.
agent_not_installed	Install and start the chosen agent, then run runinfra agents --json.
not_found	Read the named resource’s message; plan information may be unavailable.
not_entitled	Read the plan and credits before another paid action.
network, server_error, rate_limited	Wait for the returned retry delay.
config_modified without refused[]	Changed settings: follow the recovery below. Changed pending sign-in: repeat the device command and read its returned code. Unsafe pending read: review runinfra logout --local --json; after approval add --yes. Local logout does not revoke server access; revoke the old terminal key in Settings > API keys.
storage_unwritable, disk_space	Have the person fix the reported access or disk space.
checksum_mismatch, artifact_changed, range_mismatch	Stop and follow the reported recovery. Never overwrite files yourself.
interrupted, batch_incomplete	Read saved changes and run Doctor. Never repeat a failed --yes directly.
unexpected	Stop and report the message.
Plan coverage unavailable. Refresh Models.	Read runinfra models --harness <agent> --json and runinfra plan --json again.

After any failed or interrupted --yes, prepare a fresh review without --yes, show it and wait for a new yes.

Windows sign-in privacy warning

These steps are for you. Your agent must not open credential files or change permissions. With storage.restricted: false, keep the saved sign-in and inspect the named path with Get-Acl; privacy is unconfirmed. If saving failed, revoke only the unsaved terminal key named in the notice in Settings > API keys. Run runinfra whoami --json to check the sign-in still saved. Fix access before signing in again; repeated approvals can leave more unsaved keys.

You edited the agent’s settings

Keep any edits, sessions and history you need. Ask your usual agent to review runinfra disconnect <name> --force --json. It saves managed files for recovery; deleting a separate command also deletes its sessions and history. Approve only the files and key revocations you intend. Recovery copies can contain keys; keep them private.

Finish a key revocation

Doctor names the key and recovery command. Restore connections that still use it, then review runinfra keys revoke --id <keyId> --json. Add --yes only after approval. Pending revocations are not retried automatically.