CLI Reference

Complete Command Reference for OMG

This guide documents every OMG command with detailed explanations, examples, and use cases. Commands are organized by category.

---

📋 Command Overview

Category	Commands
Package Management	search, install, remove, update, info, clean, explicit, sync, why, outdated, pin, size, blame
Runtime Management	use, list, which
Shell Integration	hook, completions
Security & Audit	audit, status, doctor
Task Runner	run
Project Management	new, tool, init, self-update
Environment & Snapshots	env, snapshot, diff
Team Collaboration	team
Container Management	container
CI/CD & Migration	ci, migrate
History & Rollback	history, rollback
Dashboard	dash, stats
Configuration	config, daemon, license
Enterprise	fleet, enterprise

---

📦 Package Management

omg search

Search for packages across official repositories and AUR.

omg search <query> [OPTIONS]

Options:

Option	Short	Description
--detailed	-d	Show detailed AUR info (votes, popularity)
--interactive	-i	Interactive mode — select packages to install

Examples:

# Basic search
omg search firefox

# Interactive search (select to install)
omg search browser -i

# Detailed search with AUR votes/popularity
omg search spotify -d

Performance:

• With daemon: ~6ms
• Without daemon: ~50-200ms

---

omg install

Install packages from official repositories or AUR.

omg install <packages...> [OPTIONS]

Options:

Option	Short	Description
--yes	-y	Skip confirmation prompt

Examples:

# Install single package
omg install neovim

# Install multiple packages
omg install firefox chromium brave-bin

# Install AUR package
omg install visual-studio-code-bin

# Skip confirmation
omg install neovim -y

Security:

• Packages are graded (LOCKED, VERIFIED, COMMUNITY, RISK)
• Policy enforcement applied before installation
• PGP signatures verified for official packages

---

omg remove

Remove installed packages.

omg remove <packages...> [OPTIONS]

Options:

Option	Short	Description
--recursive	-r	Also remove unneeded dependencies

Examples:

# Remove single package
omg remove firefox

# Remove with dependencies
omg remove firefox -r

# Remove multiple packages
omg remove pkg1 pkg2 pkg3

---

omg update

Update all packages or check for updates.

omg update [OPTIONS]

Options:

Option	Short	Description
--check	-c	Only check for updates, don't install

Examples:

# Update all packages (official + AUR)
omg update

# Check for updates only
omg update --check

Update Flow:

1. Sync package databases
2. Update official packages first
3. Build and update AUR packages
4. Record transaction in history

---

omg info

Display detailed package information.

omg info <package>

Examples:

# Get info about a package
omg info firefox

# Get info about AUR package
omg info visual-studio-code-bin

Output includes:

• Package name and version
• Description
• Repository (official/AUR)
• Dependencies
• Installation status
• Security grade

Performance:

• With daemon: ~6.5ms (cached)
• Without daemon: ~50-200ms

---

omg clean

Clean package caches and remove orphaned packages.

omg clean [OPTIONS]

Options:

Option	Short	Description
--orphans	-o	Remove orphaned packages
--cache	-c	Clear package cache
--aur	-a	Clear AUR build cache
--all		Clear everything

Examples:

# Remove orphaned packages
omg clean --orphans

# Clear package cache
omg clean --cache

# Clear AUR build cache
omg clean --aur

# Full cleanup
omg clean --all

---

omg explicit

List explicitly installed packages.

omg explicit [OPTIONS]

Options:

Option	Short	Description
--count	-c	Only show count

Examples:

# List all explicit packages
omg explicit

# Get count only
omg explicit --count

Performance:

• With daemon: 1.2ms
• Without daemon: ~14ms

---

omg sync

Synchronize package databases.

omg sync

Examples:

# Sync databases
omg sync

---

omg why

Explain why a package is installed by showing its dependency chain.

omg why <package> [OPTIONS]

Options:

Option	Short	Description
--reverse	-r	Show what depends on this package

Examples:

# See why a package is installed
omg why libxcb

# See what depends on a package
omg why openssl --reverse

Output includes:

• Dependency chain from explicit packages
• Whether safe to remove
• Number of dependents

---

omg outdated

Show packages with available updates.

omg outdated [OPTIONS]

Options:

Option	Short	Description
--security	-s	Show only security updates
--json		Output as JSON

Examples:

# List all outdated packages
omg outdated

# Show only security updates
omg outdated --security

# Machine-readable output
omg outdated --json

---

omg pin

Pin packages to prevent updates.

omg pin <target> [OPTIONS]

Options:

Option	Short	Description
--unpin	-u	Remove pin
--list	-l	List all pins

Examples:

# Pin a system package
omg pin gcc

# Pin a runtime version
omg pin node@20.10.0

# List all pins
omg pin --list

# Remove a pin
omg pin gcc --unpin

---

omg size

Show disk usage by packages.

omg size [OPTIONS]

Options:

Option	Short	Description
--tree <package>	-t	Show dependency tree for package
--limit <N>	-l	Number of packages to show (default: 20)

Examples:

# Show largest packages
omg size

# Show top 50 packages
omg size --limit 50

# Show dependency tree for a package
omg size --tree firefox

---

omg blame

Show when and why a package was installed.

omg blame <package>

Examples:

# See installation history for a package
omg blame firefox

Output includes:

• Installation date/time
• Whether installed explicitly or as dependency
• Which package pulled it in (if dependency)
• Transaction ID

---

🔧 Runtime Management

omg use

Install and activate a runtime version.

omg use <runtime> [version]

Supported Runtimes:

Runtime	Aliases	Version Files
node	nodejs	.nvmrc, .node-version
bun	bunjs	.bun-version
python	python3	.python-version
go	golang	.go-version
rust	rustlang	rust-toolchain.toml
ruby		.ruby-version
java		.java-version

100+ Additional Runtimes (via built-in mise):

• Deno, Elixir, Erlang, Zig, Nim, Swift, Kotlin, .NET, PHP, Perl, Lua, Julia, R, and more

Examples:

# Install and use Node.js 20
omg use node 20.10.0

# Install and use latest LTS
omg use node lts

# Install Python 3.12
omg use python 3.12.0

# Use Rust stable
omg use rust stable

# Use Rust nightly
omg use rust nightly

# Install Deno (uses built-in mise)
omg use deno 1.40.0

# Install Elixir (uses built-in mise)
omg use elixir 1.16.0

How It Works:

1. Checks if version is installed
2. Downloads if not installed
3. Creates/updates current symlink
4. Updates PATH via shell hook

---

omg list

List installed or available runtime versions.

omg list [runtime] [OPTIONS]

Options:

Option	Short	Description
--available	-a	Show versions available for download

Examples:

# List all installed versions for all runtimes
omg list

# List installed Node.js versions
omg list node

# List available Node.js versions
omg list node --available

# List available Python versions
omg list python --available

---

omg which

Show which version of a runtime would be used.

omg which <runtime>

Examples:

# Check active Node.js version
omg which node

# Check active Python version
omg which python

# Check active Rust version
omg which rust

Version Detection Order:

1. Project-level version file (.nvmrc, etc.)
2. Parent directory version files (walking up)
3. Global current symlink

---

🐚 Shell Integration

omg hook

Print the shell hook script.

omg hook <shell>

Supported Shells:

• zsh
• bash
• fish

Examples:

# Get Zsh hook
omg hook zsh

# Add to ~/.zshrc
eval "$(omg hook zsh)"

# Add to ~/.bashrc
eval "$(omg hook bash)"

# Add to ~/.config/fish/config.fish
omg hook fish | source

Hook Features:

• PATH modification on directory change
• Runtime version detection
• Ultra-fast package count functions

---

omg completions

Generate shell completion scripts.

omg completions <shell> [OPTIONS]

Options:

Option	Description
--stdout	Print to stdout instead of installing

Examples:

# Install Zsh completions
omg completions zsh > ~/.zsh/completions/_omg

# Install Bash completions
omg completions bash > /etc/bash_completion.d/omg

# Install Fish completions
omg completions fish > ~/.config/fish/completions/omg.fish

---

🛡️ Security & Audit

omg audit

Security audit suite with multiple subcommands.

omg audit [SUBCOMMAND]

Subcommands:

Subcommand	Description
scan	Scan for vulnerabilities (default)
sbom	Generate CycloneDX 1.5 SBOM
secrets	Scan for leaked credentials
log	View audit log entries
verify	Verify audit log integrity
policy	Show security policy status
slsa <pkg>	Check SLSA provenance

Options for log:

Option	Short	Description
--limit	-l	Number of entries to show (default: 20)
--severity	-s	Filter by severity (debug, info, warning, error, critical)
--export	-e	Export logs to a file (CSV or JSON)

Examples:

# Vulnerability scan (default)
omg audit
omg audit scan

# Generate SBOM with vulnerabilities
omg audit sbom --vulns
omg audit sbom -o sbom.json

# Scan for secrets
omg audit secrets
omg audit secrets -p /path/to/project

# View audit log
omg audit log
omg audit log --limit 50
omg audit log --severity error

# Export audit logs
omg audit log --export audit.csv
omg audit log --export security_report.json

# Verify log integrity
omg audit verify

# Show policy status
omg audit policy

# Check SLSA provenance
omg audit slsa /path/to/package.pkg.tar.zst

---

omg status

Display system status overview.

omg status

Output includes:

• Package counts (total, explicit, orphans)
• Available updates
• Active runtime versions
• Security vulnerabilities
• Daemon status

---

omg doctor

Run system health checks.

omg doctor

Checks performed:

• PATH configuration
• Shell hook installation
• Daemon connectivity
• Mirror availability
• PGP keyring status
• Runtime integrity

---

🏃 Task Runner

omg run

Run project tasks with automatic runtime detection.

omg run <task> [-- <args...>] [OPTIONS]

Options:

Option	Short	Description
--watch	-w	Watch mode: re-run task on file changes
--parallel	-p	Run multiple comma-separated tasks in parallel
--runtime-backend <backend>		Force runtime backend (native, mise, native-then-mise)

Supported Project Files:

File	Runtime	Example
package.json	npm/yarn/pnpm/bun	omg run dev → npm run dev
deno.json	deno	omg run dev → deno task dev
Cargo.toml	cargo	omg run test → cargo test
Makefile	make	omg run build → make build
Taskfile.yml	task	omg run build → task build
pyproject.toml	poetry	omg run serve → poetry run serve
Pipfile	pipenv	omg run lint → pipenv run lint
composer.json	composer	omg run test → composer run-script test
pom.xml	maven	omg run test → mvn test
build.gradle	gradle	omg run test → gradle test

Examples:

# Run development server
omg run dev

# Run tests with arguments
omg run test -- --verbose

# Watch mode - re-run on file changes
omg run test --watch

# Run multiple tasks in parallel
omg run build,test,lint --parallel

# Force mise backend
omg run --runtime-backend mise dev

JavaScript Package Manager Priority:

1. packageManager field in package.json
2. Lockfile detection: bun.lockb → pnpm-lock.yaml → yarn.lock → package-lock.json
3. Default: bun (if available) → npm

---

🏗️ Project Management

omg new

Create new projects from templates.

omg new <stack> <name>

Available Stacks:

Stack	Description
rust	Rust CLI project
react	React + Vite + TypeScript
node	Node.js project
python	Python project
go	Go project

Examples:

# Create Rust CLI project
omg new rust my-cli

# Create React project
omg new react my-app

# Create Node.js API
omg new node api-server

---

omg tool

Manage cross-ecosystem CLI tools.

omg tool <SUBCOMMAND>

Subcommands:

Subcommand	Description
install <name>	Install a tool
list	List installed tools
remove <name>	Remove a tool
update <name>	Update a tool (or all to update everything)
search <query>	Search for tools in the registry
registry	Show all available tools grouped by category

Examples:

# Install ripgrep
omg tool install ripgrep

# Install jq
omg tool install jq

# List installed tools
omg tool list

# Remove a tool
omg tool remove ripgrep

# Update all tools
omg tool update all

# Search for docker-related tools
omg tool search docker

# Browse all available tools
omg tool registry

Tool Registry:

OMG includes a curated registry of 60+ popular developer tools across categories:

• search: ripgrep, fd, fzf
• files: bat, eza
• git: delta, lazygit
• system: htop, btop, dust, duf, procs
• dev: hyperfine, tokei, just, watchexec
• node: yarn, pnpm, tsx, nodemon, prettier, eslint
• rust: cargo-watch, cargo-edit, cargo-nextest, bacon
• python: black, ruff, mypy, poetry
• docker: dive, lazydocker
• deploy: vercel, netlify-cli, wrangler

Tool Resolution:

1. Check the built-in registry for optimal source
2. Fall back to interactive selection if not in registry
3. Install to isolated ~/.local/share/omg/tools/

---

omg init

Interactive first-run setup wizard.

omg init [OPTIONS]

Options:

Option	Description
--defaults	Use defaults, no prompts
--skip-shell	Skip shell hook setup
--skip-daemon	Skip daemon setup

Examples:

# Interactive setup
omg init

# Non-interactive with defaults
omg init --defaults

# Skip shell configuration
omg init --skip-shell

Setup includes:

1. Shell detection and hook installation
2. Daemon startup preference
3. Initial environment capture
4. Completion installation

---

omg self-update

Update OMG to the latest version.

omg self-update [aliases: up]

Features:

• Atomic Binary Replacement: Replaces the current binary with the latest version from releases.pyro1121.com.
• Progress Tracking: Real-time progress bar showing download speed and estimated time remaining.
• Verification: Automatically verifies the signature of the downloaded binary before installation.

Examples:

# Update OMG
omg self-update

# Using alias
omg up

---

omg config

Get or set configuration values.

omg config [key] [value]

Examples:

# List all configuration
omg config

# Get a specific value
omg config data_dir

# Set a value
omg config default_shell zsh

Configuration options:

• data_dir — Data directory path
• socket — Daemon socket path
• default_shell — Default shell for hooks
• telemetry — Enable/disable telemetry

---

📸 Environment & Snapshots

omg snapshot

Create and restore environment snapshots.

omg snapshot <SUBCOMMAND>

Subcommands:

Subcommand	Description
create	Create a new snapshot
list	List all snapshots
restore <id>	Restore a snapshot
delete <id>	Delete a snapshot

Examples:

# Create snapshot with message
omg snapshot create -m "Before major upgrade"

# List snapshots
omg snapshot list

# Preview restore
omg snapshot restore abc123 --dry-run

# Restore snapshot
omg snapshot restore abc123

# Delete old snapshot
omg snapshot delete abc123

---

omg diff

Compare two environment lock files.

omg diff [OPTIONS] <to>

Options:

Option	Short	Description
--from <file>	-f	First file (default: current environment)

Examples:

# Compare current env to a lock file
omg diff teammate-omg.lock

# Compare two lock files
omg diff --from old.lock new.lock

Output shows:

• Packages added
• Packages removed
• Version changes
• Runtime differences

---

🤝 Team Collaboration

omg env

Manage environment lockfiles.

omg env <SUBCOMMAND>

Subcommands:

Subcommand	Description
capture	Capture current state to omg.lock
check	Check for drift against omg.lock
share	Share via GitHub Gist
sync <url>	Sync from a shared Gist

Examples:

# Capture current environment
omg env capture

# Check for drift
omg env check

# Share environment (requires GITHUB_TOKEN)
export GITHUB_TOKEN=your_token
omg env share

# Sync from shared environment
omg env sync https://gist.github.com/user/abc123

---

omg team

Team workspace management.

omg team <SUBCOMMAND>

Subcommands:

Subcommand	Description
init <team-id>	Initialize team workspace
join <url>	Join existing team
status	Show team sync status
push	Push local environment to team
pull	Pull team environment
members	List team members
dashboard	Interactive team TUI
invite	Generate invite link
roles	Manage roles and permissions
propose	Propose environment changes
review	Review proposed changes
golden-path	Manage setup templates
compliance	Check compliance status
activity	View team activity stream
notify	Manage webhook notifications

Examples:

# Initialize team workspace
omg team init mycompany/frontend --name "Frontend Team"

# Join existing team
omg team join https://github.com/mycompany/env-config

# Check status
omg team status

# Push changes
omg team push

# Pull updates
omg team pull

# List members
omg team members

# Generate invite
omg team invite --email new@company.com --role developer

# Propose a change
omg team propose "Add Node.js 22 for new features"

# Review proposals
omg team review 42 --approve

# Create golden path template
omg team golden-path create frontend-setup --node 20 --packages "eslint prettier"

# Check compliance
omg team compliance --export json

# View activity
omg team activity --days 30

# Add Slack notification
omg team notify add slack https://hooks.slack.com/xxx

Roles: admin, lead, developer, readonly

---

🐳 Container Management

omg container

Docker/Podman integration.

omg container <SUBCOMMAND>

Subcommands:

Subcommand	Description
status	Show container runtime status
shell	Interactive dev shell
run <image>	Run command in container
build	Build container image
init	Generate Dockerfile
list	List running containers
images	List images
pull <image>	Pull image
stop <container>	Stop container
exec <container>	Execute in container

Examples:

# Check container runtime
omg container status

# Interactive dev shell
omg container shell

# Run command in container
omg container run alpine -- echo "hello"

# Build image
omg container build -t myapp

# Generate Dockerfile
omg container init

# List containers
omg container list

# Stop container
omg container stop mycontainer

---

🔄 CI/CD & Migration

omg ci

Generate CI/CD configuration for your project.

omg ci <SUBCOMMAND>

Subcommands:

Subcommand	Description
init <provider>	Generate CI config (github, gitlab, circleci)
validate	Validate environment matches CI expectations
cache	Show recommended cache paths

Examples:

# Generate GitHub Actions workflow
omg ci init github

# Generate GitLab CI config
omg ci init gitlab

# Validate CI environment
omg ci validate

# Get cache paths for CI
omg ci cache

Generated config includes:

• OMG installation step
• Cache configuration keyed to omg.lock
• Environment validation
• Task execution via omg run

---

omg migrate

Cross-distro migration tools.

omg migrate <SUBCOMMAND>

Subcommands:

Subcommand	Description
export	Export environment to portable manifest
import <file>	Import from manifest

Examples:

# Export current environment
omg migrate export -o my-setup.json

# Preview import
omg migrate import my-setup.json --dry-run

# Import and install
omg migrate import my-setup.json

Manifest includes:

• All installed packages with versions
• Runtime versions
• Configuration settings
• Automatic package name mapping between distros

---

🏢 Enterprise Features

omg fleet

Fleet management for multi-machine environments.

omg fleet <SUBCOMMAND>

Subcommands:

Subcommand	Description
status	Show fleet health across machines
push	Push configuration to fleet
remediate	Auto-fix drift across fleet

Examples:

# View fleet status
omg fleet status

# Push config to all machines
omg fleet push -m "Security update"

# Push to specific team
omg fleet push --team frontend

# Preview remediation
omg fleet remediate --dry-run

# Apply remediation with confirmation
omg fleet remediate --confirm

Status shows:

• Compliance percentage
• Machines by state (compliant, drifted, offline)
• Team breakdown

---

omg enterprise

Enterprise administration features.

omg enterprise <SUBCOMMAND>

Subcommands:

Subcommand	Description
reports	Generate executive reports
policy	Manage hierarchical policies
audit-export	Export compliance evidence
license-scan	Scan for license compliance
server	Self-hosted server management

Examples:

# Generate monthly report
omg enterprise reports --type monthly --format pdf

# Export SOC2 compliance evidence
omg enterprise audit-export --format soc2 --period 2025-Q4

# Scan for license issues
omg enterprise license-scan --export spdx

# Set organization policy
omg enterprise policy set --scope org "require_pgp=true"

# Show current policies
omg enterprise policy show

# Initialize self-hosted server
omg enterprise server init --license KEY --domain pkg.company.com --storage /data

Report types: monthly, quarterly, custom Compliance frameworks: soc2, iso27001, fedramp, hipaa, pci-dss

---

📜 History & Rollback

omg history

View transaction history.

omg history [OPTIONS]

Options:

Option	Short	Description
--limit <N>	-l	Number of entries (default: 20)

Examples:

# View recent history
omg history

# View last 5 transactions
omg history --limit 5

---

omg rollback

Rollback to a previous state.

omg rollback [transaction-id]

Examples:

# Interactive rollback
omg rollback

# Rollback specific transaction
omg rollback abc123

---

📊 Dashboard

omg dash

Launch interactive TUI dashboard.

omg dash

Keyboard Controls:

Key	Action
q	Quit
r	Refresh
Tab	Switch view

---

omg stats

Display usage statistics.

omg stats

---

🔑 License & Daemon

omg license

License management for Pro features.

omg license <SUBCOMMAND>

Subcommands:

Subcommand	Description
status	Show license status
activate <key>	Activate license
deactivate	Deactivate license
check <feature>	Check feature availability

---

omg daemon

Start the background daemon.

omg daemon

For direct daemon control:

omgd --foreground  # Run in foreground
omgd --socket /path/to/socket  # Custom socket path

---

⚡ Ultra-Fast Queries

omg-fast

Instant system queries for shell prompts.

omg-fast <subcommand>

Subcommands:

Subcommand	Description	Latency
status	System status	3ms
ec	Explicit count	<1ms
tc	Total count	<1ms
uc	Updates count	<1ms
oc	Orphan count	<1ms

Examples:

# Get package counts for shell prompt
omg-fast ec
omg-fast tc

# Full status
omg-fast status

---

🌍 Global Options

These options work with all commands:

Option	Short	Description
--help	-h	Show help
--version	-V	Show version

---

📚 See Also

• Quick Start Guide
• Configuration
• Runtime Management
• Security & Compliance