@every-env/spiral-cli

A command-line interface for Spiral, the agent that writes in your voice.

Quickstart

npx @every-env/spiral-cli@latest login
spiral write "a tweet about shipping fast" --instant

That's it. login opens a browser to authenticate, write produces a draft in your voice.

Installation

# Run directly (no install needed)
npx @every-env/spiral-cli@latest --help

# Or install globally
npm install -g @every-env/spiral-cli

Requires Node.js >= 18.

Authentication

API key (recommended)

# Open a browser to authenticate (recommended)
spiral login

# Or pass an API key directly
spiral login --token spiral_sk_...

# Check status
spiral auth status

# Logout
spiral logout

spiral login and spiral logout are shortcuts for spiral auth login and spiral auth logout — use whichever reads better.

Get your API key at app.writewithspiral.com/settings/api-keys.

Environment variable

For CI/CD and agent environments:

export SPIRAL_TOKEN=spiral_sk_...

SPIRAL_TOKEN takes precedence over any token stored by spiral login, so you can override locally-stored credentials without logging out.

Usage

Write content

spiral write "a blog post about shipping fast"         # Interactive (may ask questions)
spiral write "a tweet about AI" --instant               # Skip clarifying questions
spiral write "make it shorter" --session <id>           # Refine existing drafts
spiral write "..." --style <id> --workspace <id>        # With style and workspace
spiral write "..." --num-drafts 3                       # Multiple variations
spiral write "..." --instant --json                     # Machine-readable output
echo "prompt" | spiral write --instant --json           # Piped input

Personalize and humanize existing text

Two single-shot commands for transforming text you already have. Both never ask clarifying questions, take ~3-8 seconds, and accept positional input or piped stdin. Use them when you don't need a full draft — just a voice swap or a clean-up.

# Rewrite text in your unique writing voice (uses your Spiral style guide).
spiral personalize "their text here"
spiral personalize "their text" --style <id>            # Use a specific style
spiral personalize "their text" --channel x             # Hint a channel-specific style
echo "their text" | spiral personalize                  # Or pipe from anywhere

# Apply your writing rules + remove AI tells (em-dashes, "delve",
# hype words). No voice rewrite — just mechanical cleanup.
spiral humanize "their text here"
pbpaste | spiral humanize | pbcopy                      # Clean what's on the clipboard

By default both print plain text to stdout — perfect for piping. Add --json for the full response — personalize returns { text, style_used, quota_remaining }, humanize returns { text, quota_remaining } (no style_used, since there's no voice rewrite).

When in doubt: personalize includes the humanize cleanup as its final step, so reach for humanize only when you specifically don't want a voice rewrite.

Browse resources

spiral styles                  # List writing styles
spiral workspaces              # List workspaces
spiral sessions                # List past conversations
spiral drafts --session <id>   # View drafts from a session
spiral quota                   # Check session quota and plan
spiral prime                   # Full API documentation

Agent setup

For AI agents (Claude Code, Plus One, etc.):

spiral setup --token spiral_sk_...

This validates the token and prints a memory block for the agent to save. The block tells the installing agent when to reach for each command — write for new content, personalize for "rewrite in my voice" requests, humanize for "remove AI tells" requests — so the agent picks the right tool without the user having to spell it out every time.

File attachments

Pass reference documents directly via --file (repeatable):

spiral write "Turn this into a blog post" --file quarterly-report.xlsx --instant
spiral write "Compare these two decks" --file deck-a.pdf --file deck-b.pdf --instant

Supported formats: PDF, DOCX, PPTX, XLSX, HTML, EPub, TXT, MD, CSV, JSON, XML. Max 5 files, 10MB each. Spiral extracts text automatically — no need to paste file contents into the prompt.

Flags

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --session <id> | Session ID for multi-turn / refinement | | --style <id> | Writing style ID | | --workspace <id> | Workspace ID | | --file <path> | Attach a file (PDF, DOCX, XLSX, etc.) — repeatable | | --instant | Skip clarifying questions | | --num-drafts <n> | Number of drafts (1-5, default 1) | | --channel <c> | Channel hint for personalize style auto-select (x, linkedin, blog, ...) | | --token <key> | API key for auth/setup | | --debug | Show debug info on errors | | --help, -h | Show help | | --version, -v | Show version |

Agent-native usage

spiral-cli is designed to work in any environment — terminals, Docker containers, subprocess shells, CI pipelines. In non-interactive environments (no TTY), it automatically:

• Skips spinners and terminal animations
• Outputs plain text without ANSI color codes
• Returns raw markdown instead of terminal-formatted text
• Times out stdin reads to avoid hanging

# Typical agent workflow
spiral prime                                            # Get API docs
spiral styles --json                                    # Discover styles
spiral write "a launch tweet" --instant --json           # Generate content
spiral write "make it punchier" --session <id> --json    # Refine
spiral personalize "$USER_TEXT" --json                   # Rewrite in user's voice
spiral humanize "$USER_TEXT" --json                      # Strip AI tells, no voice rewrite

Exit codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Authentication required | | 3 | API error (quota, rate limit, timeout) | | 4 | Network error | | 5 | Invalid arguments |

Subscription required

The Spiral API is paid-only. Each call to spiral write, spiral personalize, or spiral humanize requires:

1. An authenticated session (spiral login).
2. A paid Spiral plan (Personal, Team, or an active Every Bundle subscription).

If a request can't be served, the CLI prints a clear next step:

• Invalid or expired API key (HTTP 401): Invalid or expired API key. Run \spiral auth login` to re-authenticate.`
• Free-tier account (HTTP 402): a Stripe Checkout link to subscribe — open it in your browser, complete payment, and re-run your command.
• Paid plan over quota (HTTP 402, Personal only): a Stripe Checkout link for a one-time top-up. Team and Trial accounts get a clear quota message but no top-up link (those tiers don't support one-off top-ups; subscribe to a Personal plan, wait for the period to reset, or contact your team admin).

In --json mode the same information is returned in structured form so agents can parse it:

{
  "error": "ApiError",
  "message": "A Spiral subscription is required to use the API. Visit app.writewithspiral.com and upgrade to a paid plan.",
  "statusCode": 402,
  "upgrade_url": "https://checkout.stripe.com/c/pay/cs_test_..."
}

When the URL points at Stripe Checkout, the post-payment redirect lands on a public confirmation page that tells the user to return to the CLI — useful when the browser isn't signed in to Spiral, or is signed in as a different account than the CLI's API key.

Environment variables

| Variable | Description | |----------|-------------| | SPIRAL_TOKEN | Auth token (alternative to spiral login; takes precedence when set) | | SPIRAL_API_URL | Override API endpoint (default: https://api.writewithspiral.com) |

Writing styles

Create writing styles at app.writewithspiral.com/writing-styles to customize Spiral's output to match your voice.

License

MIT