ahrefs-cli

command module

v0.1.0 Latest Latest Go to latest Published: Feb 17, 2026 License: MIT Imports: 4 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/aminemat/ahrefs-cli

Links

Open Source Insights

README ¶

Ahrefs CLI

AI agent-first command-line interface for the Ahrefs API v3.

🎯 Project Goals

This CLI was built with one primary mission: make the Ahrefs API maximally discoverable and usable for AI coding agents.

Why AI agents? Because if an AI can use your CLI without reading docs, humans definitely can too.

Core Principles

Discoverability First - Every command is self-documenting
Machine-Readable - All metadata available as structured JSON
Validation Before Execution - Dry-run mode for every command
Minimal Dependencies - Only Cobra + Go stdlib
Structured Errors - Rich error messages with suggestions

⚡ Quick Start

Installation

# Install with Go
go install github.com/aminemat/ahrefs-cli@latest

# Or clone and build
git clone https://github.com/aminemat/ahrefs-cli
cd ahrefs-cli
make build

Set Your API Key

# Save to config file (~/.ahrefsrc)
ahrefs config set-key YOUR_API_KEY_HERE

# Or use environment variable
export AHREFS_API_KEY=YOUR_API_KEY_HERE

Your First Query

# Get domain rating for ahrefs.com (free test query)
ahrefs site-explorer domain-rating --target ahrefs.com --date 2024-01-01

# Output
{
  "status": "success",
  "data": {
    "domain_rating": {
      "domain_rating": 91
    }
  },
  "meta": {
    "response_time_ms": 472
  }
}

🚀 Current Status

✅ Implemented & Tested

Foundation:

✅ HTTP client with Bearer auth
✅ Automatic retries with exponential backoff
✅ Rate limiting support
✅ Config management (~/.ahrefsrc)
✅ Multiple output formats (JSON, YAML, CSV, Table)
✅ 87.7% test coverage on HTTP client

Site Explorer Endpoints:

✅ domain-rating - Get domain rating
✅ backlinks-stats - Get backlink statistics
✅ backlinks - List backlinks (partial)

AI Agent Features:

✅ --list-commands - Full command tree as JSON
✅ --dry-run - Validate requests without executing
✅ --verbose - Debug mode
✅ Structured error responses with suggestions

🔨 In Progress

Site Explorer (Remaining):

⏳ refdomains - Referring domains
⏳ anchors - Anchor text distribution
⏳ organic-keywords - Organic keyword rankings
⏳ top-pages - Top-performing pages
⏳ outlinks-stats - Outbound link stats

Other API Categories:

⏳ Keywords Explorer
⏳ SERP Overview
⏳ Rank Tracker
⏳ Site Audit
⏳ Brand Radar

Advanced Features:

⏳ --describe flag (JSON schema for each endpoint)
⏳ --list-fields flag (available fields per endpoint)
⏳ Shell completions (bash/zsh/fish)
⏳ Pre-built binaries via GitHub Actions
⏳ Docker image

📖 Usage Guide

For AI Coding Agents

Step 1: Discover Available Commands

ahrefs --list-commands
# Returns complete command tree with all flags and examples as JSON

Step 2: Validate Before Execution

ahrefs site-explorer domain-rating \
  --target ahrefs.com \
  --date 2024-01-01 \
  --dry-run

# Output: ✓ Valid request. Would call: GET https://api.ahrefs.com/v3/...

Step 3: Execute & Parse Structured Output

ahrefs site-explorer domain-rating \
  --target ahrefs.com \
  --date 2024-01-01 \
  --format json

# Always returns: {"status":"success|error", "data":{...}, "meta":{...}}

Step 4: Handle Errors Programmatically

{
  "status": "error",
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key",
    "suggestion": "Run 'ahrefs config set-key <your-key>' to configure",
    "docs_url": "https://docs.ahrefs.com/..."
  }
}

For Humans

# Get help at any level
ahrefs --help
ahrefs site-explorer --help
ahrefs site-explorer domain-rating --help

# Each command includes detailed examples
ahrefs site-explorer backlinks --help

# Switch output formats
ahrefs site-explorer domain-rating --target ahrefs.com --date 2024-01-01 --format table

# Save output to file
ahrefs site-explorer domain-rating --target ahrefs.com --date 2024-01-01 -o output.json

# Use verbose mode for debugging
ahrefs site-explorer domain-rating --target ahrefs.com --date 2024-01-01 --verbose

🧪 Testing with Free Queries

Ahrefs provides free test queries for ahrefs.com and wordcount.com:

# These are FREE (no API units consumed)
ahrefs site-explorer domain-rating --target ahrefs.com --date 2024-01-01
ahrefs site-explorer domain-rating --target wordcount.com --date 2024-01-01

# Results are capped at 100 rows
ahrefs site-explorer backlinks-stats --target ahrefs.com --date 2024-01-01

Note: Full API access requires an Ahrefs Enterprise plan.

🏗️ Architecture

ahrefs-cli/
├── cmd/                      # Command implementations
│   ├── root.go              # Root command + --list-commands
│   ├── config/              # Config management
│   └── siteexplorer/        # Site Explorer endpoints
├── pkg/
│   ├── client/              # HTTP client (87.7% test coverage!)
│   │   ├── client.go
│   │   └── client_test.go
│   ├── models/              # API response structs
│   ├── output/              # Multi-format output (JSON/YAML/CSV/Table)
│   ├── schema/              # JSON schema generator (planned)
│   └── validator/           # Request validation (planned)
├── internal/
│   └── config/              # Config file I/O (~/.ahrefsrc)
├── main.go
├── Makefile                 # make build, test, install
└── README.md

Design Decisions:

Minimal deps: Only Cobra for CLI framework
Stdlib only: HTTP, JSON, CSV, testing - all native Go
No external test deps: Pure testing package with httptest
Structured errors: Always return JSON-parseable errors

🛠️ Development

Requirements

Go 1.25+
Make (optional, for convenience targets)

Build & Test

# Build
make build

# Run tests
make test

# Get test coverage
make test-coverage

# Format code
make fmt

# Run all checks
make all

Adding New Endpoints

Add model to pkg/models/
Create command in cmd/<category>/
Wire up in main.go
Add tests
Update README

Example: See cmd/siteexplorer/siteexplorer.go:newDomainRatingCmd()

📊 Project Stats

Metric	Value
Go Version	1.25+
Dependencies	2 (cobra, pflag)
Test Coverage	87.7% (client)
Lines of Code	~1,500
Endpoints	3 (more coming!)
Output Formats	4 (JSON, YAML, CSV, Table)