> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osmedeus.org/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete command-line interface reference for Osmedeus

# CLI Reference

Complete reference for all Osmedeus command-line commands and options.

## Global Options

These options are available for all commands:

| Option         | Description                                              |
| -------------- | -------------------------------------------------------- |
| `--config`     | Path to config file (default: `~/.osmedeus/config.yaml`) |
| `--debug`      | Enable debug logging                                     |
| `--quiet`      | Suppress non-essential output                            |
| `--no-color`   | Disable colored output                                   |
| `--help`, `-h` | Show help                                                |

## run

Execute workflows against targets.

### Basic Usage

```bash theme={null}
# Run a flow
osmedeus run -f <flow_name> -t <target>

# Run a module
osmedeus run -m <module_name> -t <target>

# Run multiple modules
osmedeus run -m <module1> -m <module2> -t <target>

# Run with target file
osmedeus run -f general -T targets.txt
```

### Options

| Option           | Short | Description                                              |
| ---------------- | ----- | -------------------------------------------------------- |
| `--flow`         | `-f`  | Flow workflow to run                                     |
| `--module`       | `-m`  | Module workflow to run (repeatable)                      |
| `--target`       | `-t`  | Target to scan                                           |
| `--targets`      | `-T`  | File containing targets                                  |
| `--params`       | `-P`  | Params file (YAML)                                       |
| `--param`        | `-p`  | Single param (key=value, repeatable)                     |
| `--concurrency`  | `-c`  | Concurrent target scans (default: 1)                     |
| `--timeout`      |       | Run timeout (e.g., 2h, 30m)                              |
| `--repeat`       |       | Repeat execution continuously                            |
| `--exclude`      | `-x`  | Exclude modules (comma-separated)                        |
| `--threads-hold` |       | Override thread count                                    |
| `--dry-run`      |       | Validate without executing                               |
| `--progress-bar` | `-G`  | Show progress bar during execution (enables silent mode) |
| `--workspace`    | `-w`  | Custom workspace name                                    |
| `--resume`       |       | Resume from previous state                               |

### Chunk Mode Options

For distributed scanning across multiple machines:

| Option            | Description                                 |
| ----------------- | ------------------------------------------- |
| `--chunk-size N`  | Split targets into chunks of N targets each |
| `--chunk-count N` | Split targets into N equal chunks           |
| `--chunk-part M`  | Execute only chunk M (0-indexed)            |
| `--chunk-threads` | Override concurrency within chunk           |

### Advanced Options

| Option                     | Description                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `--skip-validation`        | Skip target type validation from dependencies.variables              |
| `--disable-workflow-state` | Disable writing workflow YAML to output directory                    |
| `--heuristics-check`       | Heuristics check level: `none`, `basic`, `advanced` (default: basic) |
| `--module-url`             | URL to fetch module YAML from (supports GitHub private repos)        |
| `--std-module`             | Read module YAML from stdin                                          |

### Examples

```bash theme={null}
# Basic flow scan
osmedeus run -f general -t example.com

# Module with parameters
osmedeus run -m subdomain-enum -t example.com -p threads=20

# Multiple targets with concurrency
osmedeus run -f general -T targets.txt -c 5

# With timeout
osmedeus run -m vuln-scan -t example.com --timeout 2h

# Exclude modules in flow
osmedeus run -f general -t example.com -x port-scan,vuln-scan

# Dry run (validate only)
osmedeus run -f general -t example.com --dry-run

# With progress bar
osmedeus run -f general -t example.com -G

# Skip target validation
osmedeus run -m custom-module -t special://target --skip-validation

# Load module from URL
osmedeus run --module-url https://github.com/user/repo/blob/main/module.yaml -t example.com

# Read module from stdin
cat my-module.yaml | osmedeus run --std-module -t example.com

# Advanced heuristics checking
osmedeus run -f general -t example.com --heuristics-check advanced
```

### Chunk Mode Examples

```bash theme={null}
# Split 1000 targets into chunks of 100 (creates 10 chunks)
# Machine 1: process chunk 0 (targets 0-99)
osmedeus run -f general -T large-targets.txt --chunk-size 100 --chunk-part 0

# Machine 2: process chunk 1 (targets 100-199)
osmedeus run -f general -T large-targets.txt --chunk-size 100 --chunk-part 1

# Split into exactly 5 equal chunks
osmedeus run -f general -T large-targets.txt --chunk-count 5 --chunk-part 0

# Override concurrency within chunk
osmedeus run -f general -T large-targets.txt --chunk-size 50 --chunk-part 0 --chunk-threads 10

# View chunk info without executing (omit --chunk-part)
osmedeus run -f general -T large-targets.txt --chunk-size 100
```

Chunk mode variables available in workflows: `{{ChunkIndex}}`, `{{ChunkSize}}`, `{{TotalChunks}}`, `{{ChunkStart}}`, `{{ChunkEnd}}`

***

## workflow

Manage and inspect workflows.

### workflow list

List all available workflows.

```bash theme={null}
osmedeus workflow list
osmedeus workflow ls
```

**Options:**

| Option            | Description                      |
| ----------------- | -------------------------------- |
| `--tags`          | Filter by tags (comma-separated) |
| `--show-tags`     | Show tags column in output       |
| `--verbose`, `-v` | Show workflows with errors       |

**Examples:**

```bash theme={null}
# List all workflows
osmedeus workflow ls

# Filter by tags
osmedeus workflow ls --tags recon,fast

# Show tags column
osmedeus workflow ls --show-tags
```

### workflow show

Display workflow details.

```bash theme={null}
osmedeus workflow show <workflow_name>
```

**Options:**

| Option            | Description                            |
| ----------------- | -------------------------------------- |
| `--verbose`, `-v` | Show detailed variable descriptions    |
| `--yaml`          | Show raw YAML with syntax highlighting |

**Examples:**

```bash theme={null}
# Show workflow details
osmedeus workflow show subdomain-enum

# Show raw YAML
osmedeus workflow show subdomain-enum --yaml

# Verbose with all variables
osmedeus workflow show subdomain-enum -v
```

### workflow validate / lint

Validate and lint workflow YAML files.

```bash theme={null}
osmedeus workflow validate <name|path|folder>
osmedeus workflow lint <name|path|folder>
```

**Options:**

| Option        | Description                                   |
| ------------- | --------------------------------------------- |
| `--check`     | Exit with error code if issues found (for CI) |
| `--format`    | Output format: `pretty`, `json`, `github`     |
| `--severity`  | Minimum severity: `info`, `warning`, `error`  |
| `--disable`   | Disable rules (comma-separated)               |
| `--fail-fast` | Stop on first validation failure              |

**Lint Rules:**

| Rule                     | Severity | Description                                |
| ------------------------ | -------- | ------------------------------------------ |
| `missing-required-field` | warning  | Required fields (name, kind, type) missing |
| `duplicate-step-name`    | warning  | Multiple steps with same name              |
| `empty-step`             | warning  | Step has no executable content             |
| `unused-variable`        | info     | Variable exported but never used           |
| `undefined-variable`     | warning  | Variable referenced but not defined        |
| `invalid-goto`           | warning  | Decision goto references non-existent step |
| `invalid-depends-on`     | warning  | depends\_on references non-existent step   |
| `circular-dependency`    | warning  | Circular step dependencies detected        |

**Examples:**

```bash theme={null}
# Validate by workflow name
osmedeus workflow validate subdomain-enum

# Validate YAML file
osmedeus workflow lint ./my-workflow.yaml

# Validate all workflows in folder
osmedeus workflow validate /path/to/workflows/

# CI mode - exit with error if issues found
osmedeus workflow lint my-workflow.yaml --check

# JSON output for tooling
osmedeus workflow lint my-workflow.yaml --format json

# GitHub Actions annotations
osmedeus workflow lint . --format github

# Only show warnings and errors
osmedeus workflow lint . --severity warning

# Disable specific rules
osmedeus workflow lint . --disable unused-variable,empty-step

# Stop on first error
osmedeus workflow validate . --fail-fast
```

**JSON Output Format:**

```json theme={null}
{
  "file_path": "workflows/test.yaml",
  "issues": [
    {
      "rule": "undefined-variable",
      "severity": "warning",
      "message": "Variable 'unknown_var' is not defined",
      "suggestion": "Check that the variable is defined in params or a previous step's exports",
      "line": 15,
      "column": 12,
      "field": "steps[2].command"
    }
  ],
  "errors": 0,
  "warnings": 1,
  "infos": 0
}
```

**GitHub Actions Format:**

```
::warning file=workflows/test.yaml,line=15,col=12::undefined-variable: Variable 'unknown_var' is not defined
```

***

## func

Execute and inspect utility functions.

### func list

List all available utility functions.

```bash theme={null}
osmedeus func list
osmedeus func ls
```

**Options:**

| Option       | Description                        |
| ------------ | ---------------------------------- |
| `--category` | Filter by category                 |
| `--search`   | Search function names/descriptions |

### func execute

Execute a function expression.

```bash theme={null}
osmedeus func execute '<expression>'
osmedeus func e '<expression>'
```

**Examples:**

```bash theme={null}
# Check file exists
osmedeus func e 'fileExists("/tmp/test.txt")'

# Count lines
osmedeus func e 'fileLength("/path/to/file.txt")'

# String operations
osmedeus func e 'trim("  hello  ")'

# With variables
osmedeus func e 'log_info("{{target}}")' -p target=example.com
```

***

## eval

Shorthand for `osmedeus func eval`. Execute function expressions directly.

```bash theme={null}
osmedeus eval -e 'fileExists("/tmp/test.txt")'
osmedeus e -e 'log_info("Hello")'
```

**Aliases:** `e`, `ev`, `evl`, `evla`

***

## server

Start the REST API server.

```bash theme={null}
osmedeus server
```

**Options:**

| Option     | Description                     |
| ---------- | ------------------------------- |
| `--port`   | Server port (default: 8080)     |
| `--host`   | Bind address (default: 0.0.0.0) |
| `--master` | Run as distributed master       |
| `--token`  | API authentication token        |

**Examples:**

```bash theme={null}
# Start server
osmedeus server --port 8080

# As distributed master
osmedeus server --master --port 8080
```

***

## worker

Manage distributed workers.

### worker join

Join as a distributed worker.

```bash theme={null}
osmedeus worker join --master <master_url>
```

**Options:**

| Option     | Description          |
| ---------- | -------------------- |
| `--master` | Master server URL    |
| `--token`  | Authentication token |
| `--name`   | Worker name          |

***

## install

Install external binaries and configure environment.

### install binary

Install security tools.

```bash theme={null}
osmedeus install binary --name <binary_name>
osmedeus install binary --all
```

**Options:**

| Option                         | Description                   |
| ------------------------------ | ----------------------------- |
| `--name`                       | Specific binary to install    |
| `--all`                        | Install all binaries          |
| `--check`                      | Check installation status     |
| `--nix-build-install`          | Install via Nix               |
| `--nix-installation`           | Install Nix package manager   |
| `--list-registry-nix-build`    | List Nix-available binaries   |
| `--list-registry-direct-fetch` | List direct-download binaries |

**Examples:**

```bash theme={null}
# Install specific binary
osmedeus install binary --name nuclei

# Install all binaries
osmedeus install binary --all

# Check status
osmedeus install binary --name nuclei --check

# Install via Nix
osmedeus install binary --nix-build-install

# List available binaries
osmedeus install binary --list-registry-nix-build
```

### install env

Configure shell environment.

```bash theme={null}
osmedeus install env
osmedeus install env --all
```

**Options:**

| Option    | Description                      |
| --------- | -------------------------------- |
| `--all`   | Add to all shell configs         |
| `--shell` | Specific shell (bash, zsh, fish) |

***

## update

Self-update Osmedeus.

```bash theme={null}
osmedeus update
osmedeus update --check
```

**Options:**

| Option    | Description                          |
| --------- | ------------------------------------ |
| `--check` | Check for updates without installing |

***

## snapshot

Export and import workspace archives.

### snapshot export

Export workspace as ZIP archive.

```bash theme={null}
osmedeus snapshot export <workspace>
```

**Options:**

| Option                | Description           |
| --------------------- | --------------------- |
| `--output`            | Output file path      |
| `--include-artifacts` | Include all artifacts |

### snapshot import

Import workspace from archive.

```bash theme={null}
osmedeus snapshot import <source>
```

**Source formats:**

* Local file path
* HTTP/HTTPS URL

### snapshot list

List available snapshots.

```bash theme={null}
osmedeus snapshot list
```

***

## db

Database management commands.

### db list

List database entries.

```bash theme={null}
osmedeus db list assets
osmedeus db list vulnerabilities
osmedeus db list workspaces
```

**Options:**

| Option              | Description                             |
| ------------------- | --------------------------------------- |
| `--table, -t`       | Table name to query                     |
| `--workspace, -w`   | Filter by workspace                     |
| `--columns`         | Comma-separated column names to display |
| `--all`             | Show all columns                        |
| `--json`            | Output as JSON                          |
| `--offset`          | Number of records to skip (default: 0)  |
| `--limit`           | Maximum records to return (default: 20) |
| `--list-columns`    | List available columns for the table    |
| `--exclude-columns` | Comma-separated columns to exclude      |

### db export

Export database to file.

```bash theme={null}
osmedeus db export --workspace <name> --output <file>
```

***

## client

Interact with a remote Osmedeus server via HTTP API.

### client fetch

Fetch data from a remote server.

```bash theme={null}
osmedeus client fetch --table runs
osmedeus client fetch --table assets --workspace example_com
osmedeus client fetch --table vulnerabilities --severity critical
```

**Options:**

| Option         | Short | Description                                                                                                                            |
| -------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--remote-url` |       | Remote server URL (default: `$OSM_REMOTE_URL`)                                                                                         |
| `--auth-key`   |       | API authentication key (default: `$OSM_REMOTE_AUTH_KEY`)                                                                               |
| `--table`      | `-t`  | Table to fetch: runs, step\_results, artifacts, assets, event\_logs, schedules, workspaces, vulnerabilities, asset\_diffs, vuln\_diffs |
| `--workspace`  | `-w`  | Filter by workspace name                                                                                                               |
| `--severity`   |       | Filter vulnerabilities by severity                                                                                                     |
| `--status`     |       | Filter runs by status                                                                                                                  |
| `--limit`      |       | Maximum records (default: 20)                                                                                                          |
| `--offset`     |       | Pagination offset (default: 0)                                                                                                         |
| `--refresh`    |       | Auto-refresh interval (e.g., 5s, 1m)                                                                                                   |
| `--json`       |       | Output as JSON instead of table                                                                                                        |

### client run

Create or cancel runs on a remote server.

```bash theme={null}
osmedeus client run --workflow general --target example.com
osmedeus client run --cancel --run-id abc123
```

### client exec

Execute functions on a remote server.

```bash theme={null}
osmedeus client exec -e 'fileLength("/path/to/file")'
```

***

## health

Check system health and configuration.

```bash theme={null}
osmedeus health
```

**Checks performed:**

* Configuration file status
* Database connectivity
* External binaries availability
* Workflows loaded count
* Disk space
* Network connectivity

***

## Usage Examples

Show all usage examples.

```bash theme={null}
osmedeus --usage-example
```

This displays comprehensive examples for all major use cases.

***

## Environment Variables

| Variable              | Description                                |
| --------------------- | ------------------------------------------ |
| `OSM_CONFIG`          | Config file path                           |
| `OSM_BASE`            | Base folder path                           |
| `OSM_WORKSPACES`      | Workspaces folder path                     |
| `OSM_DEBUG`           | Enable debug mode                          |
| `OSM_TOKEN`           | API authentication token                   |
| `OSM_REMOTE_URL`      | Remote server URL for client commands      |
| `OSM_REMOTE_AUTH_KEY` | API authentication key for client commands |