Metadata-Version: 2.4
Name: gulp-cli
Version: 1.0.2
Summary: Command-line client for gULP
Author-email: Mentat <info@mentat.is>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.5
Requires-Dist: rich>=13.7.1
Requires-Dist: click==8.1.7
Requires-Dist: gulp-sdk

# 🚀 gulp-cli

> THIS IS STILL WIP! for the cli to work, set `"ws_ignore_missing": true` in your `gulp_cfg.json` to prevent the backend from halting operations when the CLI disconnects its websocket after sending an async request. This is a temporary workaround until (if)we implement a proper solution for maintaining the websocket lifecycle in the CLI.

**A modern, powerful command-line interface for gULP** — manage forensic document ingestion, querying, enrichment, and collaboration entirely from your terminal.

## ✨ What can you do?

- 🔐 **Authentication** — secure login with token persistence
- 📥 **Ingestion** — ingest files (single/batch/wildcard), zip archives, with concurrent uploads
- 🔍 **Querying** — raw OpenSearch queries, Sigma rules, external plugins
- 🏷️ **Enrichment** — enrich documents, tag/untag, update fields
- 👥 **User Management** — create users, manage permissions (admin only)
- 📋 **Operations** — create/list/manage operations and contexts
- 🔌 **Plugins** — list/upload/download plugins and mapping files
- 🗺️ **Enhance Maps** — map `gulp.event_code` to glyph/color per plugin
- 🖼️ **Glyphs** — create/list/update/delete custom glyphs
- 🧩 **Dynamic Extensions** — load custom CLI commands from internal or user extension folders
- 📊 **Stats** — monitor ingestion and query requests
- 🎯 **Collaboration** — manage notes, links, highlights

All with **beautiful terminal output**, **automatic tab completion**, and **async-first design**.

---

## 🚀 Quick Start

### Installation

```bash
# Temporary setup: gulp-sdk is currently installed from GitHub via gulp-cli dependencies.
# In the future, both gulp-sdk and gulp-cli will be installable directly from PyPI.
# for now, clone this repository and install in development mode.
# you can use your existing gulp .venv or create a new one ...
python3 -m venv ./.venv
source ./.venv/bin/activate
git clone https://github.com/mentat-is/gulp-cli
cd gulp-cli && pip install -e .

# Verify installation
gulp-cli --help
```

### Basic Usage

```bash
# Login to your gULP instance
gulp-cli auth login --url http://localhost:8080 --username admin --password admin

# Check who you are
gulp-cli auth whoami

# List operations
gulp-cli operation list

# Ingest files with wildcard
gulp-cli ingest file my_operation win_evtx 'samples/win_evtx/*.evtx'

# Query documents
gulp-cli query raw my_operation --q '{"query":{"match_all":{}}}'
```
---

## 📚 Documentation

- **[Getting Started Guide](./docs/getting-started.md)** — auth, first operation, first ingest
- **[Command Reference](./docs/command-reference.md)** — all available commands and options
- **[Extensions Guide](./docs/extensions.md)** — dynamic extension loading and custom command contract
- **[Resource Management Commands](./docs/resource-management.md)** — context, source, plugin, mapping, enhance-map, glyph
- **[Practical Examples](./docs/examples.md)** — real-world workflows and recipes
- **[Troubleshooting](./docs/troubleshooting-cli.md)** — common issues and solutions

---
