Commands - xysq documentation

xysq <command> [agents...] [options]

Command	Purpose
`install`	Auth + detect + wire MCP + install skill for detected or named agents
`uninstall`	Remove xysq from all wired or named agents
`login`	Store an API key without installing
`logout`	Remove stored key
`status`	Show what’s wired
`doctor`	Read-only health check
`update-skills`	Refresh skill files only

Common flags (apply to most commands):

Flag	Purpose
`--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`, `-y`	Skip confirmation prompts
`--json`	Machine-readable output
`--verbose`, `-v`	Show every file write and HTTP call (redacted)
`--quiet`, `-q`	Errors only
`--no-color`	Disable ANSI colors
`--dry-run`	Show 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

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

Flag	Purpose
`--api-key <key>`	Provide the key non-interactively
`--replace`	Overwrite 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

Flag	Purpose
`--purge`	Also strip the xysq MCP entry from every wired agent (destructive)
`--yes`, `-y`	Skip 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

Code	Meaning
0	All green
7	Warnings only
8	At 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

Flag	Purpose
`--force`	Overwrite a delimited block even if it was edited locally

Drift detection: if you’ve edited the  ...  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)

Code	Meaning
0	Success
1	Generic / lock contention / internal error
2	Usage error (bad flag, unknown agent)
3	Auth error (invalid key, /whoami 401)
4	Network error
5	Filesystem / parse error
6	Partial success (some agents wired, some failed)
7	`doctor`: warnings only
8	`doctor`: at least one error

Documentation Index

​install

​uninstall

​login

​logout

​status

​doctor

​update-skills

​Exit codes (all commands)