Metadata-Version: 2.5
Name: offgridsec-kira-cli
Version: 0.1.1
Summary: Kira security scanner CLI — scan local repositories for vulnerabilities
Project-URL: Homepage, https://kira.offgridsec.com
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.9
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: pathspec>=0.12
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# Kira CLI

> Scan your codebase for security vulnerabilities — from the terminal.

Kira finds web vulnerabilities, exposed secrets, misconfigurations, dependency risks, infrastructure issues, and more. Results appear directly in your terminal, with a full report available on the web dashboard.

```bash
pip install offgridsec-kira-cli
kira configure
kira scan .
```

---

## Requirements

- Python 3.9+
- A Kira account ([sign up free](https://kira.offgridsec.com))

---

## Installation

```bash
# Standard
pip install offgridsec-kira-cli

# Recommended for global CLI tools
pipx install offgridsec-kira-cli
```

---

## Getting started

**1. Create an API key**

Visit [kira.offgridsec.com/settings](https://kira.offgridsec.com/settings) and generate an API key.

**2. Authenticate**

```bash
kira configure
```

You'll be prompted to paste your key. It's saved to `~/.kira/credentials`.

Alternatively, set it as an environment variable:

```bash
export KIRA_API_KEY=kira_sk_...
```

**3. Scan**

```bash
kira scan .
```

---

## Commands

| Command | Description |
|---|---|
| `kira scan [PATH]` | Scan a directory for vulnerabilities |
| `kira results SCAN_ID` | Fetch results for a completed scan |
| `kira view-report SCAN_ID` | Open scan results as an HTML report |
| `kira status [SCAN_ID]` | Check status of active scans |
| `kira stop SCAN_ID` | Stop a running scan |
| `kira configure` | Save your API key |
| `kira --version` | Print installed version |

---

### `kira scan`

```bash
kira scan .                                      # scan current directory
kira scan ./api --name payment-service           # custom project name
kira scan ./backend --output json > results.json # JSON output
kira scan . --no-wait                            # start scan, return immediately
```

| Option | Default | Description |
|---|---|---|
| `--name`, `-n` | directory name | Project name shown on dashboard |
| `--wait` / `--no-wait` | `--wait` | Wait for scan to finish |
| `--output`, `-o` | `text` | Output format: `text` or `json` |

**Exit codes:** `0` = clean, `1` = exploitable findings detected.

---

### `kira results`

```bash
kira results abc-123                  # fetch results
kira results abc-123 --output json    # as JSON
kira results abc-123 --wait           # wait if scan still running
```

---

### `kira view-report`

Renders findings as a self-contained HTML file — no server required.

```bash
kira view-report abc-123              # open in browser
kira view-report abc-123 -o out.html  # save to file
kira view-report abc-123 --wait       # wait if scan still running
kira view-report abc-123 --no-browser # print file path, don't open browser
```

---

### `kira status`

```bash
kira status           # list all active and queued scans
kira status abc-123   # check a specific scan
```

---

### `kira stop`

```bash
kira stop abc-123
```

---

## CI/CD

`kira scan` exits with code `1` when exploitable findings are detected, making it straightforward to gate deployments.

**GitHub Actions**

```yaml
- name: Kira security scan
  run: kira scan .
  env:
    KIRA_API_KEY: ${{ secrets.KIRA_API_KEY }}
```

**JSON output for custom pipelines**

```bash
kira scan . --output json | jq '.findings[] | select(.severity == "critical")'
```

---

## Also from Kira

**[kira-lite-mcp](https://github.com/Offgrid-Security-AI/kira-lite-mcp)** catches security issues in AI-generated code in real time, inside Cursor, Claude, or Codex. Fully on-device — no account required.

| | Kira CLI | kira-lite-mcp |
|---|---|---|
| Use case | Audit your full repo | Review AI-generated code as you write |
| Requires account | Yes | No |
| Runs | In terminal / CI | Inside your AI editor |

---

## Links

- Dashboard — [kira.offgridsec.com](https://kira.offgridsec.com)
- API keys — [kira.offgridsec.com/settings](https://kira.offgridsec.com/settings)
