GoAnyAPI CLI

中文 | English

The official command-line client for GoAnyAPI, built for humans and AI agents. Query website traffic, SEO metrics, search results, advertising intelligence, and account data from a terminal with OAuth or API key authentication and structured output.

Install · AI agents · Authentication · Commands · Advanced · Security

• Agent-friendly — predictable commands, machine-readable schemas, JSON output, meaningful exit codes, and no prompts during API calls.
• Always current — commands and parameters come from the GoAnyAPI online catalog instead of a stale bundled snapshot.
• Easy interactive login — OAuth Authorization Code with PKCE opens the browser and returns through a loopback callback.
• Automation-ready — API keys work naturally in CI/CD, cron, Docker, and server scripts.
• Secure credential storage — credentials use Windows Credential Locker, macOS Keychain, or Linux Secret Service.
• Per-installation authorization — each OS-user installation keeps a random client identity, so repeated logins replace the same connection while other computers remain independently revocable.
• Structured output — choose pretty JSON, compact JSON, raw responses, or only the response data field.

The server publishes the authoritative catalog. Run goanyapi list to see the current APIs.

• Node.js 20 or newer
• npm or a compatible package manager
• A GoAnyAPI account for OAuth, or a GoAnyAPI API key

npm install --global @goanyapi/cli
goanyapi --version

# 1. Sign in through the browser
goanyapi login

# 2. Verify authentication
goanyapi auth status

# 3. Discover current APIs
goanyapi list

# 4. Make a request
goanyapi traffic example.com --month 3

Browser login uses the fixed public OAuth client goanyapi-cli, resource https://api.goanyapi.com, and scope api:invoke.

Some steps require the user to finish authorization in a browser. An agent must never read, print, or copy credentials from the system credential store.

npm install --global @goanyapi/cli

Run this in a visible user terminal because it opens a browser and waits for the loopback callback:

goanyapi login

goanyapi auth status
goanyapi list --output json
goanyapi traffic example.com --month 3 --output json
goanyapi dr example.com --output json
goanyapi serp --q "open source" --gl us --output json
goanyapi credits-balance --data-only --output json

For reliable agent use, add this guidance to AGENTS.md, CLAUDE.md, or equivalent instructions:

When website, SEO, search-result, or advertising data is needed, use the
globally installed `goanyapi` CLI. Add `--output json` to API commands. Run
`goanyapi list --output json` to discover APIs and
`goanyapi describe <command> --output json` to inspect parameters. Never read
or expose saved OAuth tokens or API keys.

The agent must run as the same operating-system user that completed goanyapi login. Windows credentials are not automatically available inside WSL, Docker, another machine, or a remote agent runtime.

goanyapi login
goanyapi auth status
goanyapi logout

Access tokens refresh automatically near expiry. Logout attempts remote revocation and always removes the local credential.

macOS and Linux:

export GOANYAPI_API_KEY="ga_xxx"
goanyapi traffic example.com --month 3 --output json

PowerShell:

$env:GOANYAPI_API_KEY = "ga_xxx"
goanyapi traffic example.com --month 3 --output json

Save a key in the system credential store without placing it directly in shell history:

goanyapi auth set-key

Credential precedence is --api-key, then GOANYAPI_API_KEY, then a saved API key or OAuth credential.

goanyapi list
goanyapi list --output json
goanyapi describe traffic
goanyapi describe traffic --output json
goanyapi traffic --help

The CLI loads /api/v1/mcp/catalog. If the online catalog is unavailable or invalid, the command fails rather than using an outdated local definition.

The online catalog is the single source of truth. README does not duplicate the complete command list, so newly published APIs and child interfaces become discoverable without a documentation release:

# List every current top-level API
goanyapi list

# Show parameters, child modes, and catalog examples
goanyapi describe ads-statistics

# Invoke a child interface exposed by action + oneOf
goanyapi ads-statistics advertiser-search --keyword ai --output json

# Invoke a oneOf query mode
goanyapi transparency --domain example.com --output json

Required parameters may also be positionals when unambiguous:

goanyapi traffic --domain example.com --month 3
goanyapi traffic example.com --month 3

Catalog names accept kebab-case aliases: creativeIds, setLang, and search_type may be written as --creative-ids, --set-lang, and --search-type.

--output pretty   # Indented JSON (default)
--output json     # Compact JSON for agents and scripts
--output raw      # Original response body
--data-only       # Only the response envelope's data field

--data-only cannot be combined with --output raw. Results go to stdout; errors and update notices go to stderr.

-k, --api-key <key>       API key (or GOANYAPI_API_KEY)
    --base-url <url>       API base URL (or GOANYAPI_BASE_URL)
-o, --output <mode>        pretty, json, or raw (default: pretty)
    --data-only            Print only the response data field
    --timeout <seconds>     Request timeout (default: 45)
    --no-update             Skip automatic update for this command
-h, --help                 Show help
-V, --version              Show version

Stable releases use production endpoints. Versions containing -next use GoAnyAPI test endpoints by default.

The CLI checks its matching npm release channel during startup. Successful checks are cached for one hour; registry failures retry after five minutes and installation failures retry after fifteen minutes. When a new version is available, the CLI updates through the detected package manager, falling back to npm when it cannot identify one. The current command continues with the already-loaded version, and the next command uses the new version.

Update failures only write a warning to stderr and never block the requested command. A cross-process lock prevents concurrent agents from installing at the same time. Automatic updates are disabled when CI=true.

goanyapi update --check  # Check now without installing
goanyapi update          # Check and install now
goanyapi --no-update traffic example.com

GOANYAPI_NO_UPDATE_CHECK=1 remains supported as a legacy opt-out.

• OAuth uses Authorization Code with PKCE; the public client has no client secret.
• The callback binds only to 127.0.0.1 on a random port.
• Tokens and saved API keys use the OS-native credential service, not a plaintext project file.
• Credentials are not printed in normal output or error messages.
• CLI OAuth tokens use the REST API audience and api:invoke scope; they are not MCP tokens.
• Prefer independently revocable API keys for unattended automation.
• AI agents can make incorrect decisions. Review commands that may expose private business data and grant only the access required.

• GoAnyAPI
• GoAnyAPI CLI on npm
• Source code
• Issue tracker