Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/byfranke/sheep-ask-cli

A command-line interface for sending AI queries to sheep.byfranke.com, focused on Cyber Threat Intelligence (CTI) and general security questions.
https://github.com/byfranke/sheep-ask-cli

cybersecurity threat-intel threat-intelligence

Last synced: 26 days ago
JSON representation

A command-line interface for sending AI queries to sheep.byfranke.com, focused on Cyber Threat Intelligence (CTI) and general security questions.

Awesome Lists containing this project

README 

          
# Sheep Ask CLI



A 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.





  AI queries from your terminal, fast and secure


  Version 1.4.3 | byFranke 2026




---



**About more:** [Sheep API](https://sheep.byfranke.com/index.html#API)



## Installation



### Prerequisites



- Python 3.7 or higher

- pip package manager



### Get Sheep Ask CLI



```bash

# Run the interactive setup wizard (recommended)

curl -fsSL https://byfranke.com/ask-cli-install | bash

```



### Install from Source



```bash

# Or install manually

git clone https://github.com/byfranke/sheep-ask-cli

cd sheep-ask-cli

chmod +x sheep-ask-cli.py setup.py install.sh

bash install.sh

python3 setup.py

```



## Configuration



### Secure Token Setup



Run the interactive setup wizard to configure your encrypted token:



```bash

python3 setup.py

```



The setup will:

- Ask for your [API token](https://sheep.byfranke.com/discord)

- Set a master password for encryption

- Store your token encrypted in `~/.sheep-ask-cli/config.ini`

- Require the master password **only once per terminal session** (cached in `/tmp` with mode `0600`, scoped to your shell's Session ID)



### Alternative: One-time Use



For single-use or testing, you can pass the token directly:



```bash

sheep-ask --token "your_api_token_here" "What is ransomware?"

```



Or via environment variable:



```bash

export SHEEP_API_TOKEN="your_api_token_here"

sheep-ask "What is ransomware?"

```



**Security**: Your token is always encrypted and password-protected when stored.



## Usage



### Basic Usage



```bash

# Ask a question

sheep-ask "What is ransomware?"



# Multi-word question (no quotes needed)

sheep-ask What are the TTPs of APT29



# Explain a framework

sheep-ask "Explain the MITRE ATT&CK framework"

```



### Interactive Mode



Running `sheep-ask` with no question (or with `-i` / `--interactive`)

starts a persistent REPL session. The same conversation memory used by

one-shot calls is reused inside the session, so follow-ups work

naturally.



```bash

sheep-ask          # enter interactive mode

sheep-ask -i       # force interactive even when a question is provided

```



Inside the REPL, commands are bare words (no `--` prefix) and are

case-insensitive. Anything that does NOT match a command is sent to the

API as a question.



| Command          | Effect                                                         |

|------------------|----------------------------------------------------------------|

| `help`           | Show the list of in-session commands.                          |

| `exit` / `quit`  | End the session.                                               |

| `plan`           | Show your plan, status, allowed models and quota.              |

| `model`          | Show which model is active for this session.                   |

| `model `   | Switch the model for this session (`auto`, `scout`, `hunter`, `sage`). Not persisted — use `--model-default` from the shell to make it permanent. |

| `clear`          | Delete the cached conversation history.                        |

| `history`        | Print the cached conversation history.                         |

| `version`        | Print the installed Sheep Ask CLI version.                     |

| `update`         | Pull the latest release from GitHub. The session ends after the pull so the next invocation runs the updated code. |



The legacy double-dash forms (`--help`, `--clear-history`,

`--show-history`) keep working inside the REPL as aliases.



When the REPL starts, it silently checks GitHub for a newer release

and, if one is available, surfaces an "Update available" banner inside

the session panel. The check is rate-limited (once per hour per user)

and skipped silently on slow networks (5-second timeout). Type `update`

to install it.



Example session:



```text

Ask Sheep > help

Commands (bare words, case-insensitive):

  help              Show this help

  exit / quit       End the session

  plan              Show your plan and quota

  model             Show the model in use

  model       Switch model for this session

                    Tiers: auto, scout, hunter, sage

  clear             Delete the cached conversation history

  history           Show the cached conversation history



Ask Sheep > model sage

Model switched to sage for this session.



Ask Sheep > What is BGP hijacking?

[... answer rendered as a panel ...]



Ask Sheep > And how do operators detect it?      # uses turn 1 as context



Ask Sheep > exit

```



### Choose a Model



Sheep exposes four model tiers. Pick one with `--model` for a single

call; the default is `auto`, which routes the question to the right

tier on the server side.



```bash

# Default — server picks the right tier

sheep-ask "What is BGP hijacking?"



# Explicit tier for one call

sheep-ask --model scout  "Define lateral movement"

sheep-ask --model hunter "Map T1566 to known APTs"

sheep-ask --model sage   "Deep CTI on Volt Typhoon's recent campaigns"

```



| Model    | Best for                                                   |

|----------|------------------------------------------------------------|

| `auto`   | Default. Smart routing.                                    |

| `scout`  | Fast factual answers, definitions, quick lookups (8B).     |

| `hunter` | Deeper CTI analysis, MITRE mapping, correlations (17B).    |

| `sage`   | Sheep Pro and Sheep Pro Max plans (120B).                  |



> Each plan covers a subset of these tiers. Trying to pick a model not

> covered by your plan returns an error message naming the tiers you

> can use and a link to upgrade. To see your allowed models, run

> `sheep-ask plan` (next section).



#### Persisting a Default Model



To stop passing `--model` on every call, set a permanent default in

your config:



```bash

# Persist 'sage' as the default model across sessions

sheep-ask --model-default sage



# Back to auto-routing

sheep-ask --model-default auto

```



The choice is written atomically to `~/.sheep-ask-cli/config.ini`

(under the `[defaults]` section, mode `0600`). Subsequent calls and

new REPL sessions use this tier unless `--model` overrides it for a

single call or `model ` overrides it inside a session.



### Check Your Plan



```bash

# Show your plan, status, allowed models, and current-period token usage

sheep-ask plan

```



### Save Response to Markdown



```bash

# Save response to sheep_answers_YYYYMMDD_HHMMSS.md in the current directory

sheep-ask -o "What is a zero-day vulnerability?"

```



### Use a File as Context



```bash

# Use a markdown file as context before the question

sheep-ask -p report.md "Summarize the key findings"

sheep-ask --prompt incident.md "What are the IOCs mentioned?"

```



### Conversation Memory



The CLI remembers the last two question/answer pairs and prepends them

to the next prompt as context, so you can follow up without re-stating

what you were talking about.



```bash

sheep-ask "What is BGP hijacking?"

sheep-ask "Give me an example from the last five years."   # uses turn 1 as context

sheep-ask "And how do operators detect it?"                # uses turns 1-2 as context

```



Storage:



- Cache directory: `~/.sheep-ask-cli/.cache/` (mode `0700`).

- History file: `history.enc` (Fernet-encrypted) when your token is

  encrypted, `history.json` (mode `0600`) otherwise. The encryption key

  is derived from your active token via PBKDF2-SHA256 + per-install salt.

- Time-to-live: 24 hours per turn. Older entries are dropped on load.

- Per-turn cap: 200 characters of question and 600 of answer.

- Automatic downgrade: if the composed request (history + new question)

  would exceed the server's input limit, the oldest turn is dropped

  first; if it still exceeds, history is skipped for that call.



Control:



```bash

# One-off call without context (and without persisting this turn)

sheep-ask --no-context "Unrelated question — no memory needed"



# See what is currently cached

sheep-ask --show-history



# Wipe the history

sheep-ask --clear-history

```



Inside [interactive mode](#interactive-mode), the same controls are

available as bare-word commands: `history` shows the cache and `clear`

wipes it.



Notes:



- Conversation memory is opt-out per call (`--no-context`), not opt-in.

- Previous turns count as prompt tokens against your plan's quota.

  If you need to minimize cost, use `--no-context` or

  `--clear-history` between unrelated questions.

- The history is local to your machine. The Sheep API never stores

  conversation between calls.



### Cap the Response Length



Use `--max-tokens N` to keep answers short. Server-side range is 100..2000;

omit the flag to let Sheep pick automatically based on the question's

complexity.



```bash

# Short answer — useful in scripts and chatops

sheep-ask --max-tokens 200 "Summarize the impact of CVE-2024-3094 in two sentences."



# Cap a longer briefing

sheep-ask --max-tokens 1500 --model sage "Correlate the last three Volt Typhoon campaigns."

```



Values outside 100..2000 are rejected locally before the request is sent.



### Output Formats



```bash

# Pretty output (default) - panel with rendered markdown

sheep-ask "Explain phishing"



# Plain text for piping / automation

sheep-ask "Explain phishing" --format plain



# Raw JSON

sheep-ask "Explain phishing" --format json



# Rendered markdown (no panel)

sheep-ask "Explain phishing" --format markdown

```



### Session Management



```bash

# Clear the cached decrypted token for the current terminal only

sheep-ask --logout

```



### Maintenance



```bash

# Show help

sheep-ask --help



# Show version

sheep-ask --version



# Re-run the setup wizard

sheep-ask --setup



# Check for updates from GitHub

sheep-ask --update



# Initialize an empty config file (placeholder for the API token)

sheep-ask --init



# Persist a default model across sessions (see "Choose a Model")

sheep-ask --model-default sage

```



### Common Issues



1. **API Token Error**

   ```

   Error: API token is required

   ```

   Solution: Run `python3 setup.py` or set `SHEEP_API_TOKEN`.



2. **Connection Error**

   ```

   Error: Failed to connect to API server

   ```

   Solution: Check your internet connection and the API URL.



3. **Request Too Large (HTTP 422)**

   ```

   Error: Request too large or invalid format

   ```

   Solution: Use a shorter question or a smaller context file with `-p`.



4. **Timeout Error**

   ```

   Error: Request timed out

   ```

   Solution: The query is taking longer than 60s. Try again or simplify the question.



5. **Unknown Model**

   ```

   Bad Request — Unknown model: gpt4

   Valid models: auto, scout, hunter, sage

   ```

   Solution: Pass one of the four supported models with `--model`.



6. **Plan Does Not Include This Model**

   ```

   Model sage is not included in Sheep Plus.

   Models in your plan: auto, scout, hunter

   ```

   Solution: Pick a model your plan covers (run `sheep-ask plan` to

   confirm) or upgrade at https://sheep.byfranke.com/pages/store.



7. **Quota Exhausted (HTTP 402)**

   ```

   Token budget consumed for the current period.

   Usage: 300,000 / 300,000 tokens

   ```

   Solution: Wait for the period to reset or upgrade at

   https://sheep.byfranke.com/pages/store.



8. **Subscription Canceled / Access Revoked**

   ```

   ACCESS REVOKED — subscription canceled or payment failed.

   ```

   Solution: Reactivate the subscription in your billing portal or

   start fresh at https://sheep.byfranke.com/pages/store. `sheep-ask plan`

   highlights this state in red so you do not waste calls during the

   revoked window.



9. **`--max-tokens` Out of Range**

   ```

   error: --max-tokens must be between 100 and 2000

   ```

   Solution: Pick a value within the supported range. Omit the flag

   to let the server pick automatically.



10. **Old Conversation Context Bleeding In**

    Symptom: the model keeps referencing a topic from a previous

    question even though you asked something unrelated.

    Solution: run `sheep-ask --clear-history` to wipe the cached

    turns, or pass `--no-context` for one-off unrelated questions.



11. **Conversation History Not Loaded**

    Symptom: `sheep-ask --show-history` says "No conversation history

    cached" even though you just ran a question.

    Solution: history is cached only after a successful answer with a

    non-empty response. Confirm the previous call did not error out,

    and that `~/.sheep-ask-cli/.cache/` is writable (`ls -la ~/.sheep-ask-cli/`).



12. **Permission denied after running `update` (1.4.1 only)**

    Symptom: after `update` in interactive mode, the shell returns

    `zsh: permission denied: sheep-ask`. Earlier installs put the

    Python entrypoint into the git index without an executable bit;

    the `update` sync re-applied the missing bit and broke the

    `/usr/local/bin/sheep-ask` symlink.

    Solution (one-time):

    ```bash

    chmod +x ~/.sheep-ask-cli/sheep-ask-cli.py

    ```

    Then `sheep-ask` works again. Running `update` once after that

    pulls 1.4.2+, which restores the executable bit automatically on

    every future sync and stores `+x` permanently in the git index so

    new installs never hit this.



### Contributing



1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests

5. Submit a pull request



## Security Considerations



- **Never commit your API token** to version control

- Store tokens securely using the setup wizard (encrypted) or `SHEEP_API_TOKEN`

- Use restrictive permissions for config files:

  ```bash

  chmod 600 ~/.sheep-ask-cli/config.ini

  ```

- Session token cache lives in `/tmp/sheep-ask-cli-sess--` with mode `0600` and is bound to your current shell's Session ID. Run `--logout` to clear it early.