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.

​
Environment variables

VariablePurposeDefault
XYSQ_API_KEYAPI key (beats keychain at runtime; never written back)none
XYSQ_API_BASEAPI root URL (override for staging / local backend)https://api.xysq.ai
XYSQ_MCP_URLMCP server URL inlined into agent configshttps://api.xysq.ai/mcp
XYSQ_HOMEOverride the CLI’s state/cache/logs directory~/.xysq
XYSQ_HTTP_TIMEOUT_MSHTTP request timeout in milliseconds10000
XYSQ_DOWNLOAD_TIMEOUT_MSSkill zip download timeout60000
NO_COLORDisable ANSI colors (same as --no-color)unset

​
State and cache

Everything the CLI persists locally lives under ~/.xysq/ (or $XYSQ_HOME): 
~/.xysq/
├── state.json            # what's wired where, skill version, last validation
├── skills-cache/v8/      # downloaded skill files, keyed by version
├── backups/              # pre-modification copies of every config file we touched
└── logs/cli-YYYY-MM-DD.log

​
state.json

Non-secret metadata. Records which agents the CLI has wired, what skill version is installed, and the last validated user identity. The API key is never stored in state.json — it lives in your OS keychain. State is treated as observation, not authority: every command re-reads each agent’s actual config file before deciding what to do. If you manually edit an MCP config and run xysq doctor, it’ll detect the change.

​
Skill cache

Downloaded skill files are cached under ~/.xysq/skills-cache/v<version>/. Re-running xysq install with no version bump on the backend hits the cache and skips the download. To force a re-fetch, delete the cache directory: 
rm -rf ~/.xysq/skills-cache
xysq update-skills

​
Backups

The first time the CLI modifies any agent config, it copies the original to ~/.xysq/backups/<agent>-<timestamp>.bak. The last 5 backups per agent are retained. To restore from a backup, copy the file back manually: 
cp ~/.xysq/backups/codex-20260516T142200Z.bak ~/.codex/config.toml

​
Logs

The CLI writes one log file per day under ~/.xysq/logs/cli-YYYY-MM-DD.log. Logs are rolled daily and retained for 14 days. All log lines redact API keys at write time (Bearer xysq_••••), so the file on disk is safe to share when filing a bug report.

​
Where the API key is stored

PlatformLocation
macOSKeychain Access — service xysq-cli, account default
WindowsCredential Manager — generic credential xysq-cli
Linuxlibsecret (Secret Service API) — service xysq-cli
Fallback (Linux without libsecret)~/.xysq/credentials with chmod 600
The key is never written to state.json, never echoed back, and never logged in plaintext. To rotate: 
xysq login --replace                   # paste new key, validates, replaces
xysq install                            # re-write every wired agent's config with the new key

​
Idempotency and atomic writes

Every command is safe to re-run. The CLI compares the current state of each config file to the desired state before writing — if nothing has changed, nothing is written. This means:
  • xysq install in a dotfiles bootstrap script is a fast no-op on every machine that’s already set up.
  • A crash mid-write leaves either the old config or the new config — never a partial. Writes go through a temp file + fsync + atomic rename.
  • A second xysq install after a Ctrl-C resumes cleanly. There’s no “repair” command needed.