surfer-cli

A CLI tool for Surfer SEO built with Go. Create content editors, run SEO audits, and check content scores from the command line.

Installation

Homebrew (macOS/Linux)

brew tap builtbyrobben/tap
brew install surfer-cli

Download Binary

Download the latest release from GitHub Releases.

Build from Source

git clone https://github.com/builtbyrobben/surfer-cli.git
cd surfer-cli
make build

Authentication

Set API Key

# Interactive (secure, recommended)
surfer-cli auth set-key --stdin

# From environment variable
echo $SURFER_API_KEY | surfer-cli auth set-key --stdin

# From argument (discouraged - exposes in shell history)
surfer-cli auth set-key YOUR_API_KEY

Check Status

surfer-cli auth status

Remove Credentials

surfer-cli auth remove

Environment Variables

• SURFER_API_KEY - Override stored credentials (also used by Surfer's official API)
• SURFER_CLI_KEYRING_BACKEND - Force keyring backend (auto/keychain/file)
• SURFER_CLI_KEYRING_PASS - Password for file backend (headless systems)

Usage

Content Editors

# List all content editors
surfer-cli editors list

# Create a new content editor
surfer-cli editors create --keywords "surfer seo guide,content optimization"

# Create with options
surfer-cli editors create --keywords "keyword1,keyword2" --language en --location "United States"

# Get editor details
surfer-cli editors get <editor-id>

# Get content score
surfer-cli editors score <editor-id>

Audits

# List all audits
surfer-cli audits list

# Create a new audit
surfer-cli audits create --url https://example.com/page

Output Formats

# JSON output (for scripting)
surfer-cli editors list --json

# Plain text output (TSV)
surfer-cli editors list --plain

API Reference

This CLI wraps the Surfer SEO API.

• Base URL: https://app.surferseo.com/api/v1
• Auth: API-KEY header

Development

Prerequisites

• Go 1.22+
• Make

Commands

make build        # Build binary
make test         # Run tests
make lint         # Run linter
make ci           # Run full CI suite
make tools        # Install dev tools

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.