# SiteData CLI Installation Guide

The following steps are intended for AI agents. Some steps require the user to complete actions in a browser. The CLI lets agents access SiteData website rankings and favorites from a terminal. The online Catalog is the authoritative source for available commands and parameters.

## Requirements

Before installation, make sure the environment has:

- Node.js 20 or later
- npm
- A [SiteData](https://sitedata.dev) account

Installation, login, and command execution must all take place under the same operating system user and in the same environment where the agent runs. Windows, WSL, Docker, remote hosts, and different operating system users do not automatically share credentials.

## Step 1: Install

```shell
npm install --global @sitedata-dev/cli
sitedata --version
```

## Step 2: Log In

The agent runs the following command, then asks the user to sign in to SiteData in the browser window that opens and approve access:

```shell
sitedata login
```

The CLI uses the OAuth Authorization Code flow with PKCE and automatically receives the local callback on `127.0.0.1`. Do not ask the user to copy an authorization code, callback URL, or token. Do not read OAuth credentials from the system credential store.

## Step 3: Verify

```shell
sitedata auth status
sitedata list --output json
```

`sitedata list` retrieves the currently available APIs from the online Catalog. To inspect the parameters and subcommands for an API:

```shell
sitedata describe rankings --output json
sitedata rankings --help
```

## Step 4: Call an API

Agents should consistently request JSON output when calling APIs:

```shell
sitedata rankings traffic-growth --output json
sitedata rankings domain-rating-growth --period archive --month 2026-08 --output json
sitedata rankings payment-traffic --gateway stripe --locale en --output json
sitedata favorites list --kind website --output json
```

Use `sitedata describe <command> --output json` before building automation because the online Catalog may publish new parameters, actions, and child interfaces without a CLI release.

## Authentication in Automated Environments

SiteData CLI currently uses interactive OAuth authentication. Before running it from a scheduled job or another automated process, complete `sitedata login` as the same operating system user and in the same environment that will run the automation.

Credentials are stored using the operating system's native credential service. They are not automatically available in another container, WSL distribution, user account, computer, or remote agent runtime. Never copy credentials into a repository, plaintext configuration file, log, or agent conversation.

To remove the saved authorization:

```shell
sitedata logout
```

For the complete command reference and troubleshooting guidance, see [SiteData CLI](https://github.com/SiteData-DEV/sitedata-cli).