spiral-cli

A command-line interface for interacting with the Spiral API from your terminal.

Installation

Prerequisites

• macOS (Safari/Chrome/Firefox cookie extraction)
• Bun >= 1.1.0
• Full Disk Access for terminal (macOS Sonoma+)

Install from npm (recommended)

# Install globally
bun add -g @every-env/spiral-cli

# Or run directly without installing
bunx @every-env/spiral-cli chat "Write a tweet about AI"

After installation, the spiral command is available globally:

spiral chat "Your prompt here"

Install from source

git clone https://github.com/EveryInc/spiral-next.git
cd spiral-next/spiral-cli
bun install

Build standalone binary

bun run build
# Output: dist/spiral

Quick Start

1. Login to Spiral at https://app.writewithspiral.com in Safari
2. Run the CLI:

# Interactive chat
bun run src/cli.ts chat

# Send a single message (agent-native)
bun run src/cli.ts send "Write a haiku about coding"

Usage

Core Commands

# Interactive chat mode
spiral chat [--session <id>] [--new]

# Send single message (non-interactive, for scripts/agents)
spiral send <message> [--session <id>] [--json] [--attach file...]

# List sessions
spiral sessions [--json] [--limit N]

# View session history
spiral history <session-id> [--json] [--limit N]

# Authentication
spiral auth status
spiral auth clear

Content Management

# Writing styles
spiral styles [--json]

# Workspaces
spiral workspaces [--json]

# Draft management
spiral drafts --session <id> [--json]
spiral draft view <id> --session <id>
spiral draft edit <id> --session <id>      # Opens in $EDITOR
spiral draft update <id> --session <id> --content "New text"  # Agent-native
spiral draft versions <id> --session <id>
spiral draft restore <id> --session <id> --versionId <vid>

Notes & Suggestions

# Local notes/scratchpad
spiral notes                    # List notes
spiral notes add "Remember X"   # Add note
spiral notes clear              # Clear all
spiral notes remove <id>        # Remove specific

# Suggestions (parsed from AI responses)
spiral suggestions              # List pending
spiral suggestions preview <id>
spiral suggestions apply <id> --session <id>
spiral suggestions dismiss <id>

Options

| Option | Description | |--------|-------------| | --help, -h | Show help | | --version, -v | Show version | | --session, -s <id> | Resume session by ID | | --json | Output as JSON (for scripting) | | --quiet, -q | Suppress spinners and progress | | --new, -n | Start new session | | --limit <N> | Limit results | | --debug, -d | Enable debug output | | --attach, -a <files> | Attach files to message | | --style <id> | Use writing style | | --workspace <id> | Use workspace context | | --force, -f | Skip confirmations | | --content <text> | Content for agent-native draft update | | --title <text> | Title for draft | | --versionId <id> | Version ID for restore |

REPL Commands (in chat mode)

| Command | Description | |---------|-------------| | /help | Show all commands | | /exit | Exit chat | | /clear | Clear screen | | /history | Show session history | | /sessions | List all sessions | | /new | Start new session | | /session <id> | Switch to session | | /debug | Toggle debug mode |

Content Management:

| Command | Description | |---------|-------------| | /drafts | List drafts in session | | /draft view <id> | View a draft | | /draft edit <id> | Edit in $EDITOR | | /draft versions <id> | Show version history | | /styles | List writing styles | | /style <id> | Set writing style | | /workspaces | List workspaces | | /workspace <id> | Set workspace |

Notes & Suggestions:

| Command | Description | |---------|-------------| | /note <text> | Add a note | | /notes | List all notes | | /notes clear | Clear all notes | | /suggestions | List pending suggestions | | /apply <id> | Apply a suggestion | | /dismiss <id> | Dismiss a suggestion | | /attach <files> | Queue files for next message |

Agent-Native Usage

spiral-cli is designed for use by AI agents and scripts:

# JSON output for parsing
spiral send "Summarize this article" --json

# Pipe input
echo "Explain quantum computing" | spiral send --json

# With file attachments
spiral send "Analyze this data" --attach data.csv --json

# Agent-native draft updates (no $EDITOR)
spiral draft update <id> --session <sid> --content "Updated content"

# Check exit codes
spiral send "Hello" && echo "Success" || echo "Failed"

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Authentication failed | | 3 | API error | | 4 | Network error | | 5 | Invalid arguments |

Environment Variables

| Variable | Description | |----------|-------------| | SPIRAL_API_URL | Override API endpoint | | SPIRAL_TOKEN | Provide auth token directly (for CI) | | EDITOR | Editor for draft editing (default: vi) | | DEBUG | Enable verbose logging |

Configuration

spiral-cli stores local configuration in ~/.config/spiral-cli/:

• Current workspace and style preferences
• Local notes/scratchpad
• Draft cache for offline editing

Authentication

spiral-cli automatically extracts your session from Safari cookies. No manual token management needed.

Requirements:

• Safari must be logged into https://app.writewithspiral.com
• Terminal needs Full Disk Access (macOS Sonoma+)

Granting Full Disk Access

1. Open System Preferences > Privacy & Security
2. Click Full Disk Access
3. Add your terminal app (Terminal.app, iTerm2, etc.)

Security Notes

• $EDITOR Integration: Only trusted editors (vim, nvim, nano, code, etc.) are allowed
• File Attachments: Path traversal and sensitive paths are blocked
• Temp Files: Created with restrictive permissions, securely deleted

Development

# Run in dev mode
bun run src/cli.ts --help

# Type check
bun run typecheck

# Run tests
bun test

# Lint
bun run lint

# Build binaries
bun run build:all

License

MIT