aic One unified TUI

Troubleshooting and FAQ

Common questions and answers grouped by topic. All commands follow Shortcuts and commands.

Install

Q: macOS / Linux install reports permission denied

A: curl | sh writes to /usr/local/bin by default. If that directory is not writable by the current user, set AIC_INSTALL_DIR:

curl -fsSL https://gitee.com/KaiyuanEra/aic-registry/raw/main/aic/install.sh \
  | AIC_INSTALL_DIR=$HOME/bin sh

Add $HOME/bin to PATH (in ~/.zshrc or ~/.bashrc).

Q: Windows install reports Expand-Archive not available

A: Expand-Archive is a built-in cmdlet in PowerShell 5.1+. Upgrade PowerShell to 5.1 or install pwsh 7+. Windows 10 1809 / Windows 11 ship with a compatible PowerShell.

Q: Checksum mismatch — what now?

A: Most likely a network intermediary corrupted the download. Re-download and verify; if it still mismatches, file a report via Contact with the Release tag, platform, and SHA256 output.

Q: GPG verification reports Can't check signature: No public key

A: Import the author’s public key first. The fingerprint is published in each Release’s release notes. Use gpg --recv-keys <fingerprint> or gpg --import <pubkey.asc>.

Sync

A: On Linux/macOS, check write permission on the target tool directories (such as .claude/ / .codex/). If they belong to another user:

sudo chown -R "$USER" .claude .codex .gemini .opencode

On Windows, without admin privileges or Developer Mode, aic automatically falls back to copy sync. No error is raised, but logs note “fallback to copy”.

Q: Windows: OPENCODE_CONFIG_DIR is not set

A: aic searches for OpenCode config in this order: OPENCODE_CONFIG_DIR → XDG_CONFIG_HOME → ~/.config/opencode. If none are set, the default path ~/.config/opencode is created automatically.

Q: After aic sync, a Skill shows BROKEN

A: The symlink source is missing (no longer present in ~/.aic/cache/skills/<name>). Repair:

aic sync               # Let aic re-pull automatically
aic update <skill>     # Or update manually

Registry

Q: Registry access times out

A: Check protocol in ~/.aic/config.toml:

protocol = "ssh"       # or "https" / "http"
ssh_key_path = "~/.ssh/id_ed25519"

For ssh, confirm that ssh_key_path points to a private key available on this machine and that ssh -T git@<host> succeeds.

Q: authentication failed

A: The current account lacks permission for the Registry repo. Contact the maintainer team rd/op/skills (see Contact).

Q: Switch to the Gitee / GitHub mirror

A: In the TUI, press , or click ⚙ to open settings and switch the Registry mirror.

You can also edit ~/.aic/config.toml:

[registry]
host = "gitee.com"      # or "github.com"
protocol = "https"

Env

Q: aic env check reports missing required variables

A: Fill them in via the Env panel:

  1. tab to the Env panel
  2. a to add a variable, then enter KEY and value
  3. c to re-check

Or via CLI:

aic env add MY_API_KEY --scope project
aic env check

Q: Promote a project-local debug variable to global

A: Use promote:

aic env promote MY_API_KEY

Q: Edited env values do not take effect

A: The active Skill / Context does not auto-reload. In the TUI, press r in the Env panel to refresh; or rerun on the CLI:

aic sync

Provider

Q: After switching Provider, the tool still uses the old config

A: Switching only updates configuration files. Restart the tool client for the change to take effect. Verify with aic list after restart.

Q: Where are backups?

A: ~/.aic/cache/<provider>/.<name>.bak. The next switch overwrites them; copy them elsewhere if you need long-term retention.

Q: My Provider profile is not listed

A: Provider profile files are created manually:

cp opencode.json opencode.json.work
# Edit opencode.json.work to adjust model / account

Refresh in the TUI’s Provider panel and aic picks it up automatically.

TUI

Q: TUI fails to start in a non-TTY environment

A: In CI / remote sessions where aic detects a non-TTY, it falls back to plain text output instead of launching the TUI. If you need to run inside a pseudo-terminal (e.g. tmux), make sure the outer wrapper is script or unbuffer.

Q: Keyboard shortcuts do not respond

A: Check:

  1. Whether the terminal emulator intercepts the keystroke (for example, certain key bindings on macOS Terminal)
  2. Whether you are in insert mode (after pressing i, some shortcuts stop working)
  3. The complete key bindings for the current panel via ctrl+?

Q: Theme switch has no visible effect

A: The theme persists to tui_theme in ~/.aic/config.toml. Changes apply to the current session immediately. If the change does not survive restart, check that the config file is writable.

Q: First keystroke after TUI start has noticeable latency

A: Usually the first Registry sync blocks startup. Wait for the sync progress bar to finish; alternatively pre-warm the cache with cd ~/.aic/cache && git fetch and the next startup will use the warm cache.

Misc

Q: How do I check the current aic version?

aic --version

Q: How do I upgrade?

# macOS / Linux
curl -fsSL https://gitee.com/KaiyuanEra/aic-registry/raw/main/aic/install.sh | AIC_VERSION=vX.Y.Z sh

Windows: irm https://gitee.com/KaiyuanEra/aic-registry/raw/main/aic/install.ps1 | iex -AICVersion vX.Y.Z.

Q: My question is not answered here

File an Issue via Contact.