# End-User Setup Guide

This guide describes how to install, configure, and launch RAVENSTRIKE.

## Prerequisites

RAVENSTRIKE runs on any platform supporting Node.js (Windows, macOS, Linux).

- **Node.js**: Version 20 or newer (download from [nodejs.org](https://nodejs.org/))
- **npm**: Version 10 or newer (automatically installed with Node.js)

Verify your Node.js version in your terminal (PowerShell, CMD, or Bash):

```bash
node --version
npm --version
```

---

## Installation & Running Methods

You can run RAVENSTRIKE either without installing it (via `npx`), or by installing it globally on your system.

### Method 1: No-Install (Quick Run via `npx`)

You can run RAVENSTRIKE instantly without global installation by prefixing commands with `npx @ravenstrike/agent`:

* **Start the Interactive Terminal Dashboard**:
  ```bash
  npx @ravenstrike/agent dashboard
  ```

* **Run a single pipeline scenario command**:
  ```bash
  npx @ravenstrike/agent run --input "suspicious encoded PowerShell" --platform QRadar
  ```

---

### Method 2: Global Installation

If you intend to use RAVENSTRIKE frequently, you can install it globally so the `ravenstrike` command is available system-wide:

1. Install the package:
   ```bash
   npm install --global @ravenstrike/agent
   ```

2. Run the application:
   * **Dashboard**:
     ```bash
     ravenstrike dashboard
     ```
   * **Command Line Interface (CLI)**:
     ```bash
     ravenstrike run --input "your threat description here" --platform CrowdStrike
     ```

---

## Configuring the LLM AI Engine

By default, RAVENSTRIKE operates in `mock` mode. It will generate deterministic outcomes based on local rule templates and does not send data over the internet or require credentials.

To enable dynamic AI generation using an OpenAI-compatible model, configure your API keys in your terminal environment.

### On Windows (PowerShell)

Set environment variables in your active terminal:

```powershell
$env:RAVENSTRIKE_LLM_PROVIDER = "openai"
$env:OPENAI_API_KEY = "your-actual-openai-api-key"
$env:RAVENSTRIKE_OPENAI_MODEL = "gpt-4.1-mini" # Optional, defaults to gpt-4.1-mini
```

### On macOS / Linux (Bash or Zsh)

```bash
export RAVENSTRIKE_LLM_PROVIDER="openai"
export OPENAI_API_KEY="your-actual-openai-api-key"
export RAVENSTRIKE_OPENAI_MODEL="gpt-4.1-mini" # Optional
```

---

## AI Assistant MCP Setup

RAVENSTRIKE natively supports the Model Context Protocol (MCP), meaning you can install it directly into AI assistants like Claude Desktop, Cursor, or Windsurf. This allows your AI to autonomously run the pipeline, draft Sigma rules, and triage scenarios using RAVENSTRIKE's tools.

### Auto-Installation (Claude Desktop)
To automatically initialize your workspace and inject the RAVENSTRIKE MCP server into Claude Desktop:

```bash
ravenstrike init-workspace
# OR
npx @ravenstrike/agent init-workspace
```

### Manual Configuration
If you are using Cursor, Windsurf, or a custom MCP client, you can configure the MCP server manually. Add the following to your tool's MCP configuration settings:

**Command**: `npx`
**Arguments**: `["-y", "@ravenstrike/agent@latest", "mcp"]`

*(Alternatively, if installed globally, you can use Command: `ravenstrike` and Arguments: `["mcp"]`)*

---

## Troubleshooting

* **Command not found (Windows)**: If the `ravenstrike` command is not recognized after global installation, restart your terminal. If it still fails, make sure the npm global bin folder is in your environment's PATH variable (typically `%USERPROFILE%\AppData\Roaming\npm`).
* **Interactive Dashboard looks distorted**: The Blessed-based terminal dashboard needs a terminal that supports ANSI formatting. We recommend using **Windows Terminal**, **VS Code Integrated Terminal**, or **macOS Terminal/iTerm2**.
* **LLM connection timed out**: If calls to OpenAI time out, you can extend the timeout limit by setting the `RAVENSTRIKE_LLM_TIMEOUT_MS` environment variable (e.g. `$env:RAVENSTRIKE_LLM_TIMEOUT_MS = "60000"` for 60 seconds).