@every-env/spiral-cli

spiral-cli

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

Installation

Prerequisites

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

Install from source

git clone <repo>
cd spiral-cli
bun install

Build standalone binary

bun run build
# Output: dist/spiral

Quick Start

• Login to Spiral at https://app.writewithspiral.com in Safari
• 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

• Open System Preferences > Privacy & Security
• Click Full Disk Access
• 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