# Set up naps-cli for an agent

Use `naps-cli` as a terminal command. Read successful results from stdout as JSON. Read errors from stderr as JSON.
Run `naps-cli agent-guide` for offline instructions.
See the [agent guide](https://github.com/JustinyAhin/naps-cli/blob/main/docs/agents.md) for command limits and cost controls.

## Install

macOS or Linux:

```sh
curl -fsSL https://naps.sh/cli/install.sh | sh
naps-cli --help
```

Windows PowerShell:

```powershell
iwr -useb https://naps.sh/cli/install.ps1 | iex
naps-cli --help
```

## Give the agent access

For `youtube-transcript --provider local`, no key is necessary.
For Naps-hosted commands, complete these steps:

1. Sign in at [naps.sh/cli](https://naps.sh/cli). Create an API key. Copy the key when it appears.
2. Set `NAPS_CLI_API_KEY` in the agent runner's secret environment. Keep the key out of prompts, command arguments, source files, and output.
3. Start or restart the agent with that environment.

New accounts receive five SEO units per day. A replacement key invalidates the old key.
If the key is missing, ask the user to set it in the runner's secret environment.

For macOS or Linux, run this command in the agent terminal. Paste the key at the hidden prompt.

```sh
printf 'Paste key: '; read -rs NAPS_CLI_API_KEY; printf '\n'; export NAPS_CLI_API_KEY
```

For Windows PowerShell, run:

```powershell
$secret = Read-Host 'Paste Naps API key' -AsSecureString
$env:NAPS_CLI_API_KEY = [System.Net.NetworkCredential]::new('', $secret).Password
```

Start or restart the agent from that terminal session.

## Commands and limits

| Service        | Access and limits                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| SEO            | Use the Naps key. Each different bulk keyword uses one SEO unit. Other keyword calls use one unit. `locations` uses none. |
| YouTube        | Try local transcripts first. DataForSEO requests require the Naps key and one SEO unit per call.                          |
| Reddit         | Use the Naps key. The account must have Reddit access.                                                                    |
| Twitter/X      | Set `NAPS_CLI_TWITTERAPI_TOKEN`, or use `--provider official` with `NAPS_CLI_X_BEARER_TOKEN`.                             |
| Search Console | Run `naps-cli search-console connect`. For headless use, supply a refresh token and matching OAuth credentials.           |

Use small result limits. When a command fails, read `error.code` and `error.hint` from stderr JSON.

## YouTube

```sh
naps-cli youtube-search 'invoicing software' --metadata
naps-cli youtube-comments Y8Wu4rSNJms --budget 0.002
naps-cli youtube-transcript Y8Wu4rSNJms --provider local --subtitles-language en
```

Search includes videos, channels, and playlists. Keep each result's `type`.
Comments contain up to 20 top comments with full text.
For transcripts, try `--provider local` first. Set `--subtitles-language` to the required language code.
Without this flag, local retrieval selects the first available track. That track can use a different language from the video.
Use text only when `available` is true. Check `originLanguage`, text, and timed segments.
Video commands accept a YouTube video URL or an 11-character video ID.

Use DataForSEO for blocked or failed local requests, invalid results, or translation.
Both providers read existing captions. Missing captions and caption errors can affect both providers.

For paid fallback, select DataForSEO and set a budget:

```sh
naps-cli youtube-transcript Y8Wu4rSNJms --provider dataforseo --subtitles-language en --budget 0.006 --metadata
```

Add `--translate-language fr` when you need French output from the selected source captions.
The CLI uses DataForSEO when `--provider` is omitted. It does not switch providers automatically.
Each DataForSEO call uses one SEO unit. The service keeps successful results for 15 minutes.
Use `--refresh` to get new results. Use `--metadata` to read cost and cache data from stderr.
`--budget 0` prevents new paid tasks. Actual charges can be higher than the estimate.
For `SEO_AMBIGUOUS_PROVIDER_OUTCOME`, stop. Request operator reconciliation before another request.

The local provider gets new captions directly from YouTube and needs no extra program.
Local `--metadata` reports zero provider cost.

See [YouTube commands](https://github.com/JustinyAhin/naps-cli/blob/main/docs/getting-started.md#youtube) for language options and output fields.

See [data and credential handling](https://naps.sh/cli/privacy) for request paths and storage details.