🚀 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), optionally compressed before upload, 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

# 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
gulp-version

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 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!

# 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 — auth, first operation, first ingest
• Command Reference — all available commands and options
• Extensions Guide — dynamic extension loading and custom command contract
• Portable Usage — offline bundles and USB-friendly layout
• Resource Management Commands — context, source, plugin, mapping, enhance-map, glyph
• Practical Examples — real-world workflows and recipes
• Troubleshooting — common issues and solutions