Skip to main content
xysq <command> [agents...] [options]
CommandPurpose
installAuth + detect + wire MCP + install skill for detected or named agents
uninstallRemove xysq from all wired or named agents
loginStore an API key without installing
logoutRemove stored key
statusShow what’s wired
doctorRead-only health check
update-skillsRefresh skill files only
Common flags (apply to most commands):
FlagPurpose
--only <a,b,c>Restrict to comma-separated agents
--skip <a,b,c>Auto-detect minus these
--api-key <key>Use this API key without prompting
--yes, -ySkip confirmation prompts
--jsonMachine-readable output
--verbose, -vShow every file write and HTTP call (redacted)
--quiet, -qErrors only
--no-colorDisable ANSI colors
--dry-runShow what would be done; touch no files

​
install

xysq install [agents...] [options]
Wires the xysq MCP server and memory skill into one or more agents. With no arguments, auto-detects every supported agent on the system and installs for those. Examples 
xysq install                                # auto-detect
xysq install codex cursor                   # positional args
xysq install --only claude-code,codex       # comma-list form
xysq install --skip claude-desktop          # auto-detect minus
xysq install --api-key xysq_... --yes --json
xysq install --dry-run                      # preview only
Behavior
  • Idempotent: re-running with no underlying changes produces zero filesystem writes.
  • Atomic: every config write goes through a temp file + rename, so a crash mid-write leaves either the old config or the new — never a partial.
  • Backup: the first time the CLI modifies any config file, it copies the original to ~/.xysq/backups/<agent>-<timestamp>.bak (last 5 per agent retained).
  • Merge-aware: existing MCP servers and other content in shared host files (AGENTS.md, GEMINI.md, .cursorrules) are preserved.

​
uninstall

xysq uninstall [agents...] [options]
Removes the xysq MCP entry and skill from every wired agent (or only the named ones). Other MCP servers and unrelated content in shared host files are preserved. Examples 
xysq uninstall                              # remove from every wired agent
xysq uninstall cursor                       # remove from cursor only
xysq uninstall --yes --json

​
login

xysq login [options]
Validate and store an API key without wiring any agents. Useful for setting up credentials in CI or before running xysq install later. Options
FlagPurpose
--api-key <key>Provide the key non-interactively
--replaceOverwrite an existing stored key
Examples 
xysq login                                  # interactive paste prompt
xysq login --api-key xysq_...               # non-interactive
xysq login --replace                        # rotate an existing key
After a successful login --replace, run xysq install to update each wired agent’s config with the new key.

​
logout

xysq logout [options]
Removes the stored API key from your keychain. Does not modify any agent’s MCP config by default — agents keep working until their next session refresh. Options
FlagPurpose
--purgeAlso strip the xysq MCP entry from every wired agent (destructive)
--yes, -ySkip the --purge confirmation prompt

​
status

xysq status [options]
Print the current state: which agents are wired, what skill version is installed, the email associated with the stored key, and whether a newer skill template is available. 
xysq · v0.1.2
Signed in as you@example.com
Skill: v8 · template 2026-05-16-b · up to date

Agent           MCP        Skill
─────────────   ────       ─────
claude-code     wired      v8
cursor          wired      v8
codex           wired      v8
antigravity     wired      –
claude-desktop  –          –
gemini-cli      –          –
copilot-cli     –          –

​
doctor

xysq doctor [agents...] [options]
Read-only health check. Verifies the stored key is valid, the xysq API is reachable, and every wired agent’s config matches what the CLI expects. Exit codes
CodeMeaning
0All green
7Warnings only
8At least one error
Doctor never modifies any file. When it flags an issue, it tells you which command to run to fix it.

​
update-skills

xysq update-skills [agents...] [options]
Re-fetch the latest skill files from api.xysq.ai/skill/download and re-install them for every wired agent (or only the named ones). MCP wiring is left untouched. Options
FlagPurpose
--forceOverwrite a delimited block even if it was edited locally
Drift detection: if you’ve edited the <!-- xysq:start --> ... <!-- xysq:end --> block in AGENTS.md, GEMINI.md, or .cursorrules since install, update-skills will warn rather than silently overwrite. --force clobbers the edit.

​
Exit codes (all commands)

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