@xevy/cli

The xevy command — set up and launch the pi agent with Xevy, the free AI workspace for digital business.

New here? Follow Get started below from top to bottom — it takes about five minutes.

Get started

1. Create your Xevy account

Xevy is free. Register (or log in if you already have an account) in the browser first:

• Register: https://xevy.ai/register
• Log in: https://xevy.ai/login

2. Make sure you have Node.js

The CLI runs on Node.js 18 or newer. Check what you have:

node --version   # should print v18.x.x or higher

If the command isn't found or the version is too old, install the latest LTS from https://nodejs.org/ and try again. npm ships with Node, so you get it automatically.

3. Install the CLI

Install globally so the xevy command is available everywhere on your machine:

npm install -g @xevy/cli

Prefer not to install anything? You can run every command below with npx @xevy/cli instead of xevy — e.g. npx @xevy/cli setup. It's slower each run but installs nothing.

4. Run the one-time setup

xevy setup

Choose exactly what to configure, or press Enter to install everything:

• Credentials — store or replace the API key in ~/.config/xevy/credentials.
• Pi — install pi and its Xevy extensions.
• Skills — install Xevy SDLC skills for selected coding agents.
• MCP — configure Xevy MCP for selected coding agents.

Codex uses a local API-key bridge, so it does not depend on expiring OAuth refresh state. Claude Code, Cursor, and other remote clients continue to use OAuth.

5. Start working

xevy                        # open an interactive pi session with Xevy loaded
xevy "summarise this repo"  # or send a one-off prompt
xevy dev task/VI22-07       # attach to a task's remote Dev Session
xevy dev xevy/xevyai       # start or resume your personal project session

That's it — you're set up. The sections below are reference for when you need more detail.

Every xevy launch checks the hosted package manifest. When an existing global skills installation is older, Xevy updates those skills before opening pi. A network or package-registry failure leaves the installed skills in place and continues the launch with a warning.

Upgrading

Keep the Xevy extensions and SDLC skills current (run after Xevy releases):

xevy check     # newer skills or missing coding-agent targets?
xevy update    # refresh the pi extensions + the SDLC skills

To upgrade the CLI binary itself:

npm update -g @xevy/cli    # or re-run: npm install -g @xevy/cli

xevy setup

xevy setup presents a component selector. Press Enter for all components, or choose any combination of credentials, Pi, skills, and MCP. The matching non-interactive flags are:

xevy setup --credentials
xevy setup --pi
xevy setup --skills --agent cursor
xevy setup --mcp --agent codex
xevy setup --component skills --component mcp --agent claude-code
xevy setup --all --yes

For a first non-interactive install, provide the key through XEVY_API_KEY=xevy_pk_… xevy setup --all --yes; the value is stored without being printed.

The components perform these actions:

1. Pi installs the agent if needed and installs the Xevy extensions:
   • xevy-core.ts (shared UI + setup/context), xevy-model.ts (the xevy/* models), and xevy-mcp.ts (the MCP→pi tool bridge) into pi's global dir ~/.pi/agent/extensions/, so they load in every pi session.
   • xevy.ts (tools + workflow commands) into ~/.xevy/extensions/.
2. Credentials asks for your API key (reuses an already-saved one if present) and prints a direct link to the API-keys tab to generate one, then stores it in ~/.config/xevy/credentials (mode 600, never printed).
3. Skills/MCP installs the Xevy SDLC skills and/or MCP server configuration for Cursor, Claude Code, and Codex by default (delegates to @xevy/skills). Pi keeps its extension-backed MCP connection, so the coding-agent configuration does not conflict with Pi.

If Pi or Codex MCP is selected without an existing API key, setup automatically adds the credentials component before making changes.

The API-keys link opens Settings → Profile → API keys directly: https://xevy.ai/settings?section=profile&tab=api.

xevy update / xevy check

xevy update    # re-download the pi extensions + update the SDLC skills
xevy check     # report skill updates or missing agent targets (exit 2 = update needed)

update refreshes the extensions from the server and the skills + MCP configuration via @xevy/skills; your saved API key is left untouched. These commands accept --base <url> for self-hosted hosts and repeatable --agent <name> overrides.

xevy

Opens pi, loading ~/.xevy/extensions via pi -e … (pi also auto-loads the global dir, so core + model + MCP come along). Before pi starts, Xevy checks the installed skills version and applies an available skills-only update. Extra arguments are forwarded to pi:

xevy                       # interactive pi session with Xevy
xevy "summarise this repo" # forwards the prompt to pi

xevy dev

Connect an interactive terminal to a task or personal remote Dev Session:

xevy dev task/VI22-07
xevy dev task/cb49c02e-66d8-4475-95a8-6f3930643ec8
xevy dev xevy/xevyai
xevy dev xevy/xevyai --base https://xevy.example.com

The command stays attached across normal Pi exits and transient terminal disconnects. After Pi exits, it waits three seconds before restarting and shows a Ctrl+C detach hint; press Ctrl+] while attached to leave the Dev Session running immediately.

The CLI grammar is explicit: task/<task-id-or-code> selects a task session, while <workspace>/<project> selects your default personal project session. Bare task IDs, aliases, and scope-guessing are intentionally unsupported. After the target is resolved, the CLI renders Pi's native TUI from the isolated remote workspace: normal composer, thinking, tools, history, keyboard shortcuts, and session resume all behave like Pi on a local machine. A multi-repository project asks for its runtime repository only on first start.

xevy dev is only a terminal transport. Pi, Git credentials, the repository, and Docker remain on the server. Press Ctrl+] to detach without stopping Pi; run the same command again to reattach. Pi conversation history is stored in the bounded Dev Session volume. The controller periodically commits work and pushes the canonical task branch; exiting Pi also commits and pushes any final edits. You do not need to ask the agent to commit after every prompt or merge a second Dev Session branch when finishing.

Terminal control:

Ctrl+]   Disconnect this terminal without stopping Pi or the Dev Session

Use the task's Dev Session panel in Xevy to open the live site, stop the session, or finish it after exiting Pi. Preview redeploy remains a separate action. A heartbeat keeps the session active while the CLI is attached, within the server's hard expiry limit.

Host precedence is --base, XEVY_BASE, the saved credentials baseUrl, then https://xevy.ai. API-key precedence is XEVY_API_KEY, then the saved key in ~/.config/xevy/credentials.

Options

      --base <url>   Xevy host (default: XEVY_BASE or https://xevy.ai)
  -a, --agent <name> Coding-agent target (repeatable; default: cursor, claude-code, codex)
  -c, --component    setup component: credentials, pi, skills, or mcp (repeatable)
      --credentials  setup credentials only (composable with other component flags)
      --pi            setup Pi only
      --skills        setup skills only
      --mcp           setup MCP only
      --all           setup every component
  -y, --yes          non-interactive; defaults to all components and agents
  -v, --version      Print the CLI version
  -h, --help         Show help

Skills & MCP for other agents

xevy setup installs the Xevy SDLC skills and MCP server for Cursor, Claude Code, and Codex by default. Target any identifier supported by skills and add-mcp with repeatable flags, for example xevy setup -a windsurf -a codex.

Codex is configured with a stable local stdio bridge that reads the revocable API key from ~/.config/xevy/credentials; restart Codex or open a new session after setup. It does not require codex mcp login xevy. In Claude Code, run /mcp and authenticate xevy. In Cursor, use Settings → MCP → xevy → Connect. Other clients expose an equivalent MCP connect/OAuth action.

You can also run the sibling package directly:

npx @xevy/skills mcp       # register the Xevy MCP server, global by default
npx @xevy/skills           # or: skills + MCP together

See the @xevy/skills README for the full command list, per-agent flags, and manual install steps.

Docs: https://xevy.ai/docs/mcp