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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.