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.

AI queries from your terminal, fast and secure
Version 1.4.3 | byFranke 2026

---

About more: Sheep API

Installation

Prerequisites

• Python 3.7 or higher
• pip package manager

Get Sheep Ask CLI

# Run the interactive setup wizard (recommended)
curl -fsSL https://byfranke.com/ask-cli-install | bash

Install from Source

# 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:

python3 setup.py

The setup will:

• Ask for your API token
• 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:

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

Or via environment variable:

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

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

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 <tier>	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:

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

# 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:

# 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 <tier> overrides it inside a session.

Check Your Plan

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

Save Response to Markdown

# 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

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

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:

# 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, 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.

# 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

# 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

# Clear the cached decrypted token for the current terminal only
sheep-ask --logout

Maintenance

# 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):

    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:

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

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