Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xysq.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
“No API key found”

The CLI couldn’t find a stored key, you didn’t pass --api-key, and XYSQ_API_KEY isn’t set in the environment. Fix: 
xysq login                           # interactive paste
# or
xysq install --api-key xysq_...      # one-shot
# or
export XYSQ_API_KEY=xysq_...
If you’re running in a non-TTY environment (CI, dotfiles bootstrap), the CLI exits with code 3 instead of prompting — you must supply the key via flag or env var.

​
”Your stored xysq API key was rejected”

The key in your keychain is no longer valid — maybe it was revoked from the dashboard, or you’ve signed in as a different user since it was generated. Fix: 
xysq login --replace                 # paste a fresh key
xysq install                          # re-sync every wired agent

​
“<file> is malformed JSON/TOML”

The CLI refuses to touch a config file that doesn’t parse. This protects you from a clobbered file when the agent’s config is mid-edit or has a stray syntax error. Fix: open the file, find the parse error (the message includes line/column), repair it, then re-run xysq install.

​
”Permission denied” on a config file

The CLI couldn’t write to an agent’s config file. 
✗ Cannot write ~/.codex/config.toml (Permission denied)
  Diagnosis: file is owned by root (perhaps installed via system package).
  Fix: `sudo chown $USER ~/.codex/config.toml` then re-run `xysq install codex`.
The CLI’s error message includes a copy-pasteable fix when it can diagnose the cause.

​
”block edited locally” warning from doctor

You manually edited the content inside the <!-- xysq:start --> ... <!-- xysq:end --> block of a shared host file (AGENTS.md, GEMINI.md, .cursorrules). The CLI flags this as drift rather than silently overwriting your edit. Fix (you want to keep your edit): ignore the warning. Edits inside the block persist as long as you don’t re-run update-skills --force. Fix (you want the CLI’s version back): 
xysq update-skills --force <agent>

​
“previously installed but MCP entry missing”

Doctor’s report when an agent was wired by a past xysq install, but the current MCP config file doesn’t contain the xysq entry. Usually means something else overwrote the file, or you ran the agent’s own “reset config” command. Fix: 
xysq install <agent>                 # re-wire

​
Agent installed but xysq install doesn’t detect it

For agents detected via dir presence (claude-code, claude-desktop, cursor, codex, antigravity), the CLI checks for a known directory. If the agent never created its config directory, detection misses it. For PATH-detected agents (gemini-cli, copilot-cli), the CLI checks for the binary on $PATH. If you installed via a path manager (asdf, fnm, etc.) that isn’t in your default shell, the binary may not be discoverable. Force-install explicitly: 
xysq install gemini-cli              # bypass detection

​
“Another xysq command is already running”

Two xysq invocations tried to acquire the state lock at the same time. The CLI waits up to 5 seconds for the lock; if the other process is genuinely hung, remove the lock file: 
rm ~/.xysq/state.json.lock
xysq install

​
Keychain unavailable on Linux

On Linux without libsecret installed, the CLI falls back to ~/.xysq/credentials with mode 0600. This works but is less secure than the system keychain. Fix (Debian/Ubuntu): 
sudo apt install libsecret-1-0 libsecret-1-dev
Fix (Fedora/RHEL): 
sudo dnf install libsecret libsecret-devel
Then run xysq login --replace to move the key to the keychain.

​
Internal error — “filing an issue”

If you hit an unhandled error, the CLI prints a trace ID and the log path: 
✗ Internal error
  This is a bug. Please file an issue at github.com/xysq-ai/xysq_cli/issues
  Trace: 8f3a2c91-e4b7-...
  Logs: ~/.xysq/logs/cli-2026-05-18.log
The log file has keys redacted at write time, so it’s safe to attach to a bug report.

​
Exit codes

The CLI uses distinct exit codes so you can tell different failure modes apart in scripts:
CodeMeaning
0Success
1Generic / lock contention / internal error
2Usage error (bad flag, unknown agent)
3Auth error (invalid key, /whoami 401)
4Network error
5Filesystem / parse error
6Partial success (some agents wired, some failed)
7doctor: warnings only
8doctor: at least one error
In CI, code 6 is the “partial” case where some agents succeeded and others failed — usually worth treating as a fatal failure for hygiene, but the unrelated successful agents are wired correctly and don’t need a re-run.