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

# 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

# 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

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

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:

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

osmedeus workflow show <workflow_name>

Options:

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

Examples:

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

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:

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

{
  "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.

osmedeus func list
osmedeus func ls

Options:

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

func execute

Execute a function expression.

osmedeus func execute '<expression>'
osmedeus func e '<expression>'

Examples:

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

osmedeus eval -e 'fileExists("/tmp/test.txt")'
osmedeus e -e 'log_info("Hello")'

Aliases: e, ev, evl, evla

server

Start the REST API server.

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:

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

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.

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:

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

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.

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.

osmedeus snapshot export <workspace>

Options:

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

snapshot import

Import workspace from archive.

osmedeus snapshot import <source>

Source formats:

Local file path
HTTP/HTTPS URL

snapshot list

List available snapshots.

osmedeus snapshot list

db

Database management commands.

db list

List database entries.

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.

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.

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.

osmedeus client run --workflow general --target example.com
osmedeus client run --cancel --run-id abc123

client exec

Execute functions on a remote server.

osmedeus client exec -e 'fileLength("/path/to/file")'

health

Check system health and configuration.

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.

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

​CLI Reference

​Global Options

​run

​Basic Usage

​Options

​Chunk Mode Options

​Advanced Options

​Examples

​Chunk Mode Examples

​workflow

​workflow list

​workflow show

​workflow validate / lint

​func

​func list

​func execute

​eval

​server

​worker

​worker join

​install

​install binary

​install env

​update

​snapshot

​snapshot export

​snapshot import

​snapshot list

​db

​db list

​db export

​client

​client fetch

​client run

​client exec

​health

​Usage Examples

​Environment Variables

CLI Reference

Global Options

run

Basic Usage

Options

Chunk Mode Options

Advanced Options

Examples

Chunk Mode Examples

workflow

workflow list

workflow show

workflow validate / lint

func

func list

func execute

eval

server

worker

worker join

install

install binary

install env

update

snapshot

snapshot export

snapshot import

snapshot list

db

db list

db export

client

client fetch

client run

client exec

health

Usage Examples

Environment Variables