# DataForSEO CLI
A dependency-free, safety-gated command-line client for the DataForSEO v3 REST API. It exposes the complete API without maintaining a second endpoint catalogue, while requiring an explicit `--execute` flag for potentially paid requests.
> [!WARNING]
> `--execute` is an authorization gate, not a spending cap. Check the endpoint's current DataForSEO pricing and review the exact payload before running a request.
This project is independent and is not affiliated with or endorsed by DataForSEO.
## Features
- Calls any relative DataForSEO v3 endpoint with `GET` or `POST`.
- Refuses potentially paid requests unless `--execute` is present.
- Rejects external URLs and refuses HTTP redirects so credentials cannot leave the DataForSEO API origin.
- Reads JSON from an argument, a file, or standard input.
- Validates top-level and task-level API status codes.
- Prints provider-reported request cost to standard error.
- Provides a sanitized account summary that excludes the account login.
- Uses only the Python standard library at runtime.
- Includes a portable [Agent Skill](skills/dataforseo-api/SKILL.md) for cost-aware use by compatible AI agents.
## Requirements
- Python 3.10 or newer
- A DataForSEO account and API credentials
The API password is generated by DataForSEO and differs from the account password. See the [official authentication documentation](https://docs.dataforseo.com/v3/auth/).
## Install
### pipx
```bash
pipx install git+https://github.com/alexferrari88/dataforseo-cli.git
```
### uv
```bash
uv tool install git+https://github.com/alexferrari88/dataforseo-cli.git
```
### From a clone
```bash
git clone https://github.com/alexferrari88/dataforseo-cli.git
cd dataforseo-cli
python3 -m pip install .
```
## Configure credentials
Environment variables take precedence:
```bash
export DATAFORSEO_API_LOGIN='your-api-login'
export DATAFORSEO_API_PASSWORD='your-api-password'
```
The aliases `DATAFORSEO_USERNAME`, `DATAFORSEO_LOGIN`, and `DATAFORSEO_PASSWORD` are also accepted.
Alternatively, create `~/.config/dataforseo-cli/env` (or `$XDG_CONFIG_HOME/dataforseo-cli/env` when `XDG_CONFIG_HOME` is set):
```dotenv
DATAFORSEO_API_LOGIN=your-api-login
DATAFORSEO_API_PASSWORD=your-api-password
```
Protect the file:
```bash
chmod 600 ~/.config/dataforseo-cli/env
```
Use a different file with the global `--env-file` option:
```bash
dfs --env-file /path/to/credentials.env account
```
## Usage
### Free sanitized account summary
```bash
dfs account
```
The command returns balance, spending, and request limits without printing the account login.
### Preflight a potentially paid request
```bash
dfs request POST /v3/dataforseo_labs/google/keyword_overview/live \
--data '[{"keywords":["example keyword"],"location_code":2840,"language_code":"en"}]'
```
The request fails closed with exit code `2` and does not load credentials or contact the API.
### Execute after reviewing scope and price
```bash
dfs request POST /v3/dataforseo_labs/google/keyword_overview/live \
--data-file payload.json \
--execute
```
The JSON response is written to standard output. The provider-reported actual cost is written to standard error.
### Read JSON from standard input
```bash
printf '%s' '[{"keywords":["example keyword"],"location_code":2840,"language_code":"en"}]' |
dfs request POST /v3/dataforseo_labs/google/keyword_overview/live \
--data-file - \
--execute
```
## Safety model
The only implicitly allowed endpoint is:
```text
GET /v3/appendix/user_data
```
All other `GET` and `POST` requests require `--execute`, because DataForSEO billing varies by product and endpoint. The CLI deliberately does not hard-code prices or infer whether an unfamiliar endpoint is free. Consult the [current API documentation](https://docs.dataforseo.com/v3/) before each new workflow.
For task-based APIs, treat `task_post` as potentially billable. Persist task IDs and do not blindly repeat a paid submission after an ambiguous timeout.
## Agent Skill
The repository ships a vendor-neutral skill following the [Agent Skills specification](https://agentskills.io/specification):
```text
skills/dataforseo-api/SKILL.md
```
Install it with a compatible skills client, for example:
```bash
npx skills add https://github.com/alexferrari88/dataforseo-cli --skill dataforseo-api
```
The skill refers only to the public `dfs` interface. It contains no machine-specific paths, private configuration, or instructions tied to one agent product.
## Development
```bash
python3 -m unittest discover -s tests -v
python3 -m compileall -q dfs_cli.py tests
```
## License
MIT. See [LICENSE](LICENSE).