respawn-cli

CLI tool for Respawn — backup and restore your Claude Code environment (~/.claude/ + ~/.claude.json).

Installation

npm install -g respawn-cli

Requires Node.js 18+.

Authentication

respawn login

Opens a browser tab. Sign in with your Respawn account, then return to the terminal. Session is saved to ~/.respawn/config.json.

Global environment (~/.claude/)

Back up and restore your entire Claude Code setup across all projects.

# Push
respawn global push                         # Upload with auto-generated message
respawn global push -m "add MCP server"    # Upload with a commit message
respawn global commit "add MCP server"     # Shorthand for global push -m
respawn global push -p standard            # Use a specific backup profile

# Pull
respawn global pull                         # Restore latest version
respawn global pull -v 3                   # Restore a specific version

# History & state
respawn global log                          # Show all versions
respawn global status                       # Show current state

Backup profiles

Controls which files are included in the backup.

| Profile | What's included | |---------|----------------| | essential (default) | Settings, plugins, MCP config. Excludes conversation history and project data. Safe for any team or machine. | | standard | Everything in essential + MEMORY.md files from your projects. Useful if you rely on persistent memory. | | full | Everything, including .jsonl conversation history. Large; best for personal machine-to-machine sync. |

respawn global push -p essential   # default
respawn global push -p standard    # + MEMORY.md files
respawn global push -p full        # + conversation history

Project environment (.claude/)

Back up and restore a single project's .claude/ folder.

Initialize

cd my-project
respawn init                    # Creates .respawnrc (uses current directory name)
respawn init --name my-app      # Custom project name
respawn init --from my-app      # Link to an existing project (same ID, continues version history)

This creates a .respawnrc file in the current directory:

{ "name": "my-app", "id": "uuid..." }

Push

respawn push                          # Upload .claude/ (auto message)
respawn push -m "add custom rules"    # Upload with a commit message
respawn commit "add custom rules"     # Shorthand for push -m

Pull

respawn pull                    # Restore latest version
respawn pull -v 2               # Restore a specific version
respawn pull -p my-app          # Pull from a named project (no .respawnrc needed)

--project creates a new .respawnrc with a fresh ID, so future pushes won't overwrite the source project.

Existing files are automatically backed up before restore (.claude.backup.{timestamp}/).

History & state

respawn log       # Show version history for this project
respawn status    # Show current project backup state

Sharing

Share your environment as a link. Anyone with the link can clone it.

respawn share                   # Share latest project backup
respawn share --global          # Share latest global backup
respawn clone <url>             # Apply a shared environment to .claude/

Example workflow:

# Person A — shares their setup
respawn share
# Sharing...
# ✓ https://respawn.run/s/a1b2c3d4

# Person B — clones it
cd new-project
respawn clone https://respawn.run/s/a1b2c3d4
# ✓ Applied environment from "person-a / v5"

Safety rules

• .env* files are always excluded from every backup, regardless of profile
• ~/.claude.json is included in global backups (stores Claude Code preferences)
• Auto-backup before restore — existing .claude/ is copied to .claude.backup.{timestamp}/ before any pull

Local files

| Path | Description | |------|-------------| | ~/.respawn/config.json | Auth tokens and user info (mode 0600) | | ./.respawnrc | Project name and ID for the current project |

Help

respawn --help
respawn global --help
respawn push --help