Metadata-Version: 2.4
Name: gulp-cli
Version: 1.1.4
Summary: Command-line client for gULP
Author-email: Mentat <info@mentat.is>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.AGPL-3.0.txt
License-File: LICENSE.md
Requires-Dist: typer==0.23.1
Requires-Dist: rich==15.0.0
Requires-Dist: click==8.3.3
Requires-Dist: gulp-sdk
Provides-Extra: portable
Requires-Dist: pyinstaller<7,>=6.11; extra == "portable"
Dynamic: license-file

# 🚀 gulp-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 document fields (e.g., `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
# from pip
pip install gulp-cli

# or install local portable-build tooling
pip install 'gulp-cli[portable]'

# or, for the latest development version:
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
```

### Portable Bundles

For offline use from a USB stick, prefer the OS-specific portable bundles built with PyInstaller instead of `pip install`.

- Each target OS needs its own bundle: Linux, Windows, macOS Intel, macOS Apple Silicon.
- Portable bundles keep config and external extensions in a local `data/` directory next to the executable.
- You can override that location with `GULP_CLI_HOME` or `--config-dir`.

See **[Portable Usage](./docs/portable.md)** for the layout, local build command, and CI artifact details.

### Basic Usage

> for the cli to work, set `"ws_ignore_missing": true` (should be default in the v1.6.51 backend, though ...) in your `gulp_cfg.json` to prevent the backend from halting operations when the CLI disconnects its websocket after sending an async request!

```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 (per-file progress is on by default; use --no-show-per-file-progress to hide it)
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
- **[Portable Usage](./docs/portable.md)** — offline bundles and USB-friendly layout
- **[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

---
