{"id":50545033,"url":"https://github.com/byfranke/sheep-ask-cli","last_synced_at":"2026-06-03T23:01:31.171Z","repository":{"id":351434142,"uuid":"1210983879","full_name":"byfranke/sheep-ask-cli","owner":"byfranke","description":"A command-line interface for sending AI queries to sheep.byfranke.com, focused on Cyber Threat Intelligence (CTI) and general security questions.","archived":false,"fork":false,"pushed_at":"2026-05-24T22:01:04.000Z","size":153,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T22:14:36.985Z","etag":null,"topics":["cybersecurity","threat-intel","threat-intelligence"],"latest_commit_sha":null,"homepage":"https://sheep.byfranke.com/discord","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/byfranke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T00:41:52.000Z","updated_at":"2026-05-24T22:01:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/byfranke/sheep-ask-cli","commit_stats":null,"previous_names":["byfranke/sheep-ask-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/byfranke/sheep-ask-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-ask-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-ask-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-ask-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-ask-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byfranke","download_url":"https://codeload.github.com/byfranke/sheep-ask-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byfranke%2Fsheep-ask-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33883102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cybersecurity","threat-intel","threat-intelligence"],"created_at":"2026-06-03T23:01:30.283Z","updated_at":"2026-06-03T23:01:31.165Z","avatar_url":"https://github.com/byfranke.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sheep Ask CLI\n\nA command-line interface for sending AI queries to [sheep.byfranke.com](https://sheep.byfranke.com), focused on Cyber Threat Intelligence (CTI) and general security questions.\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAI queries from your terminal, fast and secure\u003c/strong\u003e\u003cbr\u003e\n  Version 1.4.3 | byFranke 2026\n\u003c/p\u003e\n\n---\n\n**About more:** [Sheep API](https://sheep.byfranke.com/index.html#API)\n\n## Installation\n\n### Prerequisites\n\n- Python 3.7 or higher\n- pip package manager\n\n### Get Sheep Ask CLI\n\n```bash\n# Run the interactive setup wizard (recommended)\ncurl -fsSL https://byfranke.com/ask-cli-install | bash\n```\n\n### Install from Source\n\n```bash\n# Or install manually\ngit clone https://github.com/byfranke/sheep-ask-cli\ncd sheep-ask-cli\nchmod +x sheep-ask-cli.py setup.py install.sh\nbash install.sh\npython3 setup.py\n```\n\n## Configuration\n\n### Secure Token Setup\n\nRun the interactive setup wizard to configure your encrypted token:\n\n```bash\npython3 setup.py\n```\n\nThe setup will:\n- Ask for your [API token](https://sheep.byfranke.com/discord)\n- Set a master password for encryption\n- Store your token encrypted in `~/.sheep-ask-cli/config.ini`\n- Require the master password **only once per terminal session** (cached in `/tmp` with mode `0600`, scoped to your shell's Session ID)\n\n### Alternative: One-time Use\n\nFor single-use or testing, you can pass the token directly:\n\n```bash\nsheep-ask --token \"your_api_token_here\" \"What is ransomware?\"\n```\n\nOr via environment variable:\n\n```bash\nexport SHEEP_API_TOKEN=\"your_api_token_here\"\nsheep-ask \"What is ransomware?\"\n```\n\n**Security**: Your token is always encrypted and password-protected when stored.\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Ask a question\nsheep-ask \"What is ransomware?\"\n\n# Multi-word question (no quotes needed)\nsheep-ask What are the TTPs of APT29\n\n# Explain a framework\nsheep-ask \"Explain the MITRE ATT\u0026CK framework\"\n```\n\n### Interactive Mode\n\nRunning `sheep-ask` with no question (or with `-i` / `--interactive`)\nstarts a persistent REPL session. The same conversation memory used by\none-shot calls is reused inside the session, so follow-ups work\nnaturally.\n\n```bash\nsheep-ask          # enter interactive mode\nsheep-ask -i       # force interactive even when a question is provided\n```\n\nInside the REPL, commands are bare words (no `--` prefix) and are\ncase-insensitive. Anything that does NOT match a command is sent to the\nAPI as a question.\n\n| Command          | Effect                                                         |\n|------------------|----------------------------------------------------------------|\n| `help`           | Show the list of in-session commands.                          |\n| `exit` / `quit`  | End the session.                                               |\n| `plan`           | Show your plan, status, allowed models and quota.              |\n| `model`          | Show which model is active for this session.                   |\n| `model \u003ctier\u003e`   | Switch the model for this session (`auto`, `scout`, `hunter`, `sage`). Not persisted — use `--model-default` from the shell to make it permanent. |\n| `clear`          | Delete the cached conversation history.                        |\n| `history`        | Print the cached conversation history.                         |\n| `version`        | Print the installed Sheep Ask CLI version.                     |\n| `update`         | Pull the latest release from GitHub. The session ends after the pull so the next invocation runs the updated code. |\n\nThe legacy double-dash forms (`--help`, `--clear-history`,\n`--show-history`) keep working inside the REPL as aliases.\n\nWhen the REPL starts, it silently checks GitHub for a newer release\nand, if one is available, surfaces an \"Update available\" banner inside\nthe session panel. The check is rate-limited (once per hour per user)\nand skipped silently on slow networks (5-second timeout). Type `update`\nto install it.\n\nExample session:\n\n```text\nAsk Sheep \u003e help\nCommands (bare words, case-insensitive):\n  help              Show this help\n  exit / quit       End the session\n  plan              Show your plan and quota\n  model             Show the model in use\n  model \u003ctier\u003e      Switch model for this session\n                    Tiers: auto, scout, hunter, sage\n  clear             Delete the cached conversation history\n  history           Show the cached conversation history\n\nAsk Sheep \u003e model sage\nModel switched to sage for this session.\n\nAsk Sheep \u003e What is BGP hijacking?\n[... answer rendered as a panel ...]\n\nAsk Sheep \u003e And how do operators detect it?      # uses turn 1 as context\n\nAsk Sheep \u003e exit\n```\n\n### Choose a Model\n\nSheep exposes four model tiers. Pick one with `--model` for a single\ncall; the default is `auto`, which routes the question to the right\ntier on the server side.\n\n```bash\n# Default — server picks the right tier\nsheep-ask \"What is BGP hijacking?\"\n\n# Explicit tier for one call\nsheep-ask --model scout  \"Define lateral movement\"\nsheep-ask --model hunter \"Map T1566 to known APTs\"\nsheep-ask --model sage   \"Deep CTI on Volt Typhoon's recent campaigns\"\n```\n\n| Model    | Best for                                                   |\n|----------|------------------------------------------------------------|\n| `auto`   | Default. Smart routing.                                    |\n| `scout`  | Fast factual answers, definitions, quick lookups (8B).     |\n| `hunter` | Deeper CTI analysis, MITRE mapping, correlations (17B).    |\n| `sage`   | Sheep Pro and Sheep Pro Max plans (120B).                  |\n\n\u003e Each plan covers a subset of these tiers. Trying to pick a model not\n\u003e covered by your plan returns an error message naming the tiers you\n\u003e can use and a link to upgrade. To see your allowed models, run\n\u003e `sheep-ask plan` (next section).\n\n#### Persisting a Default Model\n\nTo stop passing `--model` on every call, set a permanent default in\nyour config:\n\n```bash\n# Persist 'sage' as the default model across sessions\nsheep-ask --model-default sage\n\n# Back to auto-routing\nsheep-ask --model-default auto\n```\n\nThe choice is written atomically to `~/.sheep-ask-cli/config.ini`\n(under the `[defaults]` section, mode `0600`). Subsequent calls and\nnew REPL sessions use this tier unless `--model` overrides it for a\nsingle call or `model \u003ctier\u003e` overrides it inside a session.\n\n### Check Your Plan\n\n```bash\n# Show your plan, status, allowed models, and current-period token usage\nsheep-ask plan\n```\n\n### Save Response to Markdown\n\n```bash\n# Save response to sheep_answers_YYYYMMDD_HHMMSS.md in the current directory\nsheep-ask -o \"What is a zero-day vulnerability?\"\n```\n\n### Use a File as Context\n\n```bash\n# Use a markdown file as context before the question\nsheep-ask -p report.md \"Summarize the key findings\"\nsheep-ask --prompt incident.md \"What are the IOCs mentioned?\"\n```\n\n### Conversation Memory\n\nThe CLI remembers the last two question/answer pairs and prepends them\nto the next prompt as context, so you can follow up without re-stating\nwhat you were talking about.\n\n```bash\nsheep-ask \"What is BGP hijacking?\"\nsheep-ask \"Give me an example from the last five years.\"   # uses turn 1 as context\nsheep-ask \"And how do operators detect it?\"                # uses turns 1-2 as context\n```\n\nStorage:\n\n- Cache directory: `~/.sheep-ask-cli/.cache/` (mode `0700`).\n- History file: `history.enc` (Fernet-encrypted) when your token is\n  encrypted, `history.json` (mode `0600`) otherwise. The encryption key\n  is derived from your active token via PBKDF2-SHA256 + per-install salt.\n- Time-to-live: 24 hours per turn. Older entries are dropped on load.\n- Per-turn cap: 200 characters of question and 600 of answer.\n- Automatic downgrade: if the composed request (history + new question)\n  would exceed the server's input limit, the oldest turn is dropped\n  first; if it still exceeds, history is skipped for that call.\n\nControl:\n\n```bash\n# One-off call without context (and without persisting this turn)\nsheep-ask --no-context \"Unrelated question — no memory needed\"\n\n# See what is currently cached\nsheep-ask --show-history\n\n# Wipe the history\nsheep-ask --clear-history\n```\n\nInside [interactive mode](#interactive-mode), the same controls are\navailable as bare-word commands: `history` shows the cache and `clear`\nwipes it.\n\nNotes:\n\n- Conversation memory is opt-out per call (`--no-context`), not opt-in.\n- Previous turns count as prompt tokens against your plan's quota.\n  If you need to minimize cost, use `--no-context` or\n  `--clear-history` between unrelated questions.\n- The history is local to your machine. The Sheep API never stores\n  conversation between calls.\n\n### Cap the Response Length\n\nUse `--max-tokens N` to keep answers short. Server-side range is 100..2000;\nomit the flag to let Sheep pick automatically based on the question's\ncomplexity.\n\n```bash\n# Short answer — useful in scripts and chatops\nsheep-ask --max-tokens 200 \"Summarize the impact of CVE-2024-3094 in two sentences.\"\n\n# Cap a longer briefing\nsheep-ask --max-tokens 1500 --model sage \"Correlate the last three Volt Typhoon campaigns.\"\n```\n\nValues outside 100..2000 are rejected locally before the request is sent.\n\n### Output Formats\n\n```bash\n# Pretty output (default) - panel with rendered markdown\nsheep-ask \"Explain phishing\"\n\n# Plain text for piping / automation\nsheep-ask \"Explain phishing\" --format plain\n\n# Raw JSON\nsheep-ask \"Explain phishing\" --format json\n\n# Rendered markdown (no panel)\nsheep-ask \"Explain phishing\" --format markdown\n```\n\n### Session Management\n\n```bash\n# Clear the cached decrypted token for the current terminal only\nsheep-ask --logout\n```\n\n### Maintenance\n\n```bash\n# Show help\nsheep-ask --help\n\n# Show version\nsheep-ask --version\n\n# Re-run the setup wizard\nsheep-ask --setup\n\n# Check for updates from GitHub\nsheep-ask --update\n\n# Initialize an empty config file (placeholder for the API token)\nsheep-ask --init\n\n# Persist a default model across sessions (see \"Choose a Model\")\nsheep-ask --model-default sage\n```\n\n### Common Issues\n\n1. **API Token Error**\n   ```\n   Error: API token is required\n   ```\n   Solution: Run `python3 setup.py` or set `SHEEP_API_TOKEN`.\n\n2. **Connection Error**\n   ```\n   Error: Failed to connect to API server\n   ```\n   Solution: Check your internet connection and the API URL.\n\n3. **Request Too Large (HTTP 422)**\n   ```\n   Error: Request too large or invalid format\n   ```\n   Solution: Use a shorter question or a smaller context file with `-p`.\n\n4. **Timeout Error**\n   ```\n   Error: Request timed out\n   ```\n   Solution: The query is taking longer than 60s. Try again or simplify the question.\n\n5. **Unknown Model**\n   ```\n   Bad Request — Unknown model: gpt4\n   Valid models: auto, scout, hunter, sage\n   ```\n   Solution: Pass one of the four supported models with `--model`.\n\n6. **Plan Does Not Include This Model**\n   ```\n   Model sage is not included in Sheep Plus.\n   Models in your plan: auto, scout, hunter\n   ```\n   Solution: Pick a model your plan covers (run `sheep-ask plan` to\n   confirm) or upgrade at https://sheep.byfranke.com/pages/store.\n\n7. **Quota Exhausted (HTTP 402)**\n   ```\n   Token budget consumed for the current period.\n   Usage: 300,000 / 300,000 tokens\n   ```\n   Solution: Wait for the period to reset or upgrade at\n   https://sheep.byfranke.com/pages/store.\n\n8. **Subscription Canceled / Access Revoked**\n   ```\n   ACCESS REVOKED — subscription canceled or payment failed.\n   ```\n   Solution: Reactivate the subscription in your billing portal or\n   start fresh at https://sheep.byfranke.com/pages/store. `sheep-ask plan`\n   highlights this state in red so you do not waste calls during the\n   revoked window.\n\n9. **`--max-tokens` Out of Range**\n   ```\n   error: --max-tokens must be between 100 and 2000\n   ```\n   Solution: Pick a value within the supported range. Omit the flag\n   to let the server pick automatically.\n\n10. **Old Conversation Context Bleeding In**\n    Symptom: the model keeps referencing a topic from a previous\n    question even though you asked something unrelated.\n    Solution: run `sheep-ask --clear-history` to wipe the cached\n    turns, or pass `--no-context` for one-off unrelated questions.\n\n11. **Conversation History Not Loaded**\n    Symptom: `sheep-ask --show-history` says \"No conversation history\n    cached\" even though you just ran a question.\n    Solution: history is cached only after a successful answer with a\n    non-empty response. Confirm the previous call did not error out,\n    and that `~/.sheep-ask-cli/.cache/` is writable (`ls -la ~/.sheep-ask-cli/`).\n\n12. **Permission denied after running `update` (1.4.1 only)**\n    Symptom: after `update` in interactive mode, the shell returns\n    `zsh: permission denied: sheep-ask`. Earlier installs put the\n    Python entrypoint into the git index without an executable bit;\n    the `update` sync re-applied the missing bit and broke the\n    `/usr/local/bin/sheep-ask` symlink.\n    Solution (one-time):\n    ```bash\n    chmod +x ~/.sheep-ask-cli/sheep-ask-cli.py\n    ```\n    Then `sheep-ask` works again. Running `update` once after that\n    pulls 1.4.2+, which restores the executable bit automatically on\n    every future sync and stores `+x` permanently in the git index so\n    new installs never hit this.\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests\n5. Submit a pull request\n\n## Security Considerations\n\n- **Never commit your API token** to version control\n- Store tokens securely using the setup wizard (encrypted) or `SHEEP_API_TOKEN`\n- Use restrictive permissions for config files:\n  ```bash\n  chmod 600 ~/.sheep-ask-cli/config.ini\n  ```\n- Session token cache lives in `/tmp/sheep-ask-cli-sess-\u003cuid\u003e-\u003csid\u003e` with mode `0600` and is bound to your current shell's Session ID. Run `--logout` to clear it early.   ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyfranke%2Fsheep-ask-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyfranke%2Fsheep-ask-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyfranke%2Fsheep-ask-cli/lists"}