# Reddit CLI — Exhaustive Agent & Developer Manual A high-performance native command-line tool and agent interface for scraping Reddit posts, comments, communities, and users via Apify. Built with Rust Edition 2024 for maximum performance, minimal cold-start latency, and reliable LLM agent tool-calling. Website: https://spacecorps.github.io/Reddit-Cli/ Repository: https://github.com/SpaceCorps/Reddit-Cli Version: 1.0.0 --- ## 1. Output & Error Protocol Reddit CLI adheres to the SpaceCorps Agentic Output Standard: - **Default Format:** YAML on stdout (high human and LLM readability). - **JSON Flag (`--json`):** Pretty-printed JSON on stdout with preserved key order for parsing via `jq` or agent automation loops. - **Diagnostics & Status:** Human status updates (e.g. "Searching Reddit...") and warning banners are routed to stderr, ensuring stdout remains pure, parseable data. - **Error Envelopes:** Errors are written to stderr in a structured format: ```json { "error": "The API token was rejected or expired.", "code": "auth_required", "detail": "HTTP 401: Unauthorized", "remediation": "reddit login --api-key --force" } ``` ### Exit Codes | Code | Name | Description | Agent Action | |---|---|---|---| | 0 | `ok` | Command completed successfully. | Proceed with next task. | | 1 | `error` | General or unclassified error. | Inspect error message; report to human if unrecoverable. | | 2 | `network` | Network connection error or Apify timeout. | Retry once with backoff; then report. | | 3 | `auth_required` | Missing, invalid, or expired API token. | Do NOT retry; ask human to provide token or run `reddit login`. | | 4 | `not_found` | Resource or URL not found. | Verify URL or arguments; do not retry same call. | | 5 | `rate_limited` | Apify rate limit encountered. | Back off exponentially before retrying. | | 6 | `invalid_input` | Missing required argument or illegal combination. | Fix CLI flags according to usage error. | | 7 | `no_account` | Named account not found or multiple accounts exist. | Run `reddit accounts list` to check account names. | --- ## 2. Authentication Architecture Requests to Apify's actor API require an API token. The CLI resolves tokens according to this hierarchy: 1. `--api-key ` passed directly on the command line. 2. `--account ` (or `-a `) referencing an account securely stored in the host operating system's keystore. 3. `APIFY_TOKEN` or `REDDIT_API_KEY` environment variables. 4. If exactly one account is stored in the local config, that account is automatically used. 5. If multiple accounts exist without `--account`, exit code 7 (`no_account`) lists available accounts. ### Secure Keystores Tokens are stored encrypted: - **macOS:** macOS Keychain via `/usr/bin/security`. - **Windows:** Data Protection API (DPAPI). - **Linux:** Secret Service API via `secret-tool` (GNOME Keyring, KWallet). - **Headless / Plaintext Fallback:** Enabled only when `REDDIT_ALLOW_PLAINTEXT_STORE=1` is explicitly set. --- ## 3. Command Reference ### `reddit search [OPTIONS]` Searches Reddit for submissions, comments, subreddits, or users. **Arguments:** - `` (Required): Search query string. **Options:** - `--community `: Restrict search to a specific subreddit (e.g. `rust` or `technology`). - `--comments`: Search for comments matching query instead of posts. - `--communities`: Search for subreddits matching query. - `--users`: Search for Reddit usernames matching query. - `--sort `: Sort order: `relevance`, `hot`, `top`, `new`, `rising`, `comments` (Default: `new`). - `--time