Complete reference for the catty command-line interface.
catty login
Authenticate with Catty via your browser.
Opens your default browser for authentication. Supports email, Google, and enterprise SSO.
Credentials are stored at ~/.catty/credentials.json.
You only need to log in once. Tokens are automatically refreshed.
catty logout
Remove stored credentials.
Deletes ~/.catty/credentials.json. Run catty login to authenticate again.
catty new
Start a new Claude Code session.
Flags
| Flag | Description |
|---|
--no-upload | Don’t upload current directory to the session |
--no-sync-back | Disable real-time sync of remote changes to local |
--api <url> | Override API URL (for development) |
--agent codex | Use Codex instead of Claude Code (experimental) |
Examples
# Standard session - uploads current directory
catty new
# Start without uploading workspace
catty new --no-upload
# Start without sync-back
catty new --no-sync-back
# Combine flags
catty new --no-upload --no-sync-back
# Use local API (development)
catty new --api http://127.0.0.1:4815
Behavior
- Creates a new cloud machine
- Uploads current directory (unless
--no-upload)
- Starts Claude Code in
/workspace
- Connects your terminal via WebSocket
- Enables sync-back (unless
--no-sync-back)
Exit
Press Ctrl+C or type /exit in Claude Code to disconnect.
catty connect
Reconnect to an existing session.
catty connect <label> [flags]
Arguments
| Argument | Description |
|---|
label | Session label (e.g., brave-tiger-1234) |
Flags
| Flag | Description |
|---|
--no-sync-back | Disable sync-back for this connection |
Examples
# Reconnect to a session
catty connect brave-tiger-1234
# Reconnect without sync-back
catty connect brave-tiger-1234 --no-sync-back
Get session labels from catty list.
catty list
List all your sessions.
Output
Shows a table with:
- Session label
- Status (running, stopped)
- Created timestamp
Example Output
LABEL STATUS CREATED
brave-tiger-1234 running 2 hours ago
swift-falcon-5678 stopped 1 day ago
clever-dolphin-9012 running 5 minutes ago
catty stop
Stop a running session.
Arguments
| Argument | Description |
|---|
label | Session label to stop |
Example
catty stop brave-tiger-1234
Stopping a session destroys the cloud machine. Files not synced back are lost.
catty version
Print the CLI version.
Example Output
Environment Variables
| Variable | Description | Default |
|---|
CATTY_API_ADDR | Override API URL | https://catty-api.fly.dev |
Example
# Use local API
export CATTY_API_ADDR=http://127.0.0.1:4815
catty new
Exit Codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | General error |
| 2 | Authentication required (run catty login) |
Global Behavior
Authentication
All commands except login, logout, and version require authentication. If not logged in, you’ll see:
Error: Not logged in. Run 'catty login' to authenticate.
Token Refresh
If your access token expires during a command, Catty automatically refreshes it using the stored refresh token. This happens transparently.
| Platform | Architecture |
|---|
| macOS | Intel (amd64), Apple Silicon (arm64) |
| Linux | x64 (amd64), ARM64 |
Windows support is not yet available.
