CLI Reference

Complete reference for all Invowk™ command-line commands and flags.

Global Flags

These flags are available for all commands:

Flag	Short	Description
--help	-h	Show help for the command
--ivk-config	-c	Config file path (default: $HOME/.config/invowk/config.cue)
--ivk-interactive	-i	Run commands in alternate screen buffer (interactive mode)
--ivk-verbose	-v	Enable verbose output
--version		Show version information (root command only, not inherited by subcommands)

Commands

invowk

The root command. Running invowk without arguments shows the help message.

invowk [flags]
invowk [command]

---

invowk cmd

Execute commands defined in invowkfiles.

invowk cmd [flags]
invowk cmd [command-name] [flags] [-- args...]

Flags:

Flag	Short	Description
--ivk-runtime	-r	Override the runtime (must be allowed by the command)
--ivk-from	-f	Source to run command from (e.g., 'invowkfile' or module name)
--ivk-force-rebuild		Force rebuild of container images (container runtime only)
--ivk-dry-run		Print resolved execution plan without executing
--ivk-watch	-W	Watch mode: re-execute on file changes

Built-in per-command flags:

Flag	Short	Description
--ivk-env-file	-e	Load environment variables from file (repeatable)
--ivk-env-var	-E	Set environment variable (KEY=VALUE, repeatable)
--ivk-env-inherit-mode		Inherit host environment variables: none, allow, all
--ivk-env-inherit-allow		Allowlist host env vars to inherit (repeatable)
--ivk-env-inherit-deny		Denylist host env vars to inherit (repeatable)
--ivk-workdir	-w	Override working directory for this command

note

The ivk-, invowk-, and i- prefixes are reserved for system flags and cannot be used for user-defined flags.

Examples:

# List all available commands
invowk cmd

# Run a command
invowk cmd build

# Run a nested command
invowk cmd test unit

# Run with a specific runtime
invowk cmd build --ivk-runtime container

# Run with arguments
invowk cmd greet -- "World"

# Run with flags
invowk cmd deploy --env production

# Watch mode (re-execute on file changes)
invowk cmd dev --ivk-watch
invowk cmd dev -W

# Dry-run mode (print execution plan, don't execute)
invowk cmd build --ivk-dry-run

Command Discovery:

Commands are discovered from (in priority order):

1. Current directory invowkfile.cue (highest priority)
2. Sibling *.invowkmod module directories
3. Configured includes entries (modules only)
4. ~/.invowk/cmds/ (modules only, non-recursive)

Command Disambiguation:

When a command name exists in multiple sources (e.g., both invowkfile.cue and a module), you must disambiguate:

Using @source prefix:

invowk cmd @invowkfile deploy      # Run deploy from invowkfile
invowk cmd @tools deploy         # Run deploy from tools.invowkmod
invowk cmd @tools.invowkmod deploy # Full module name also works

Using --ivk-from flag:

invowk cmd --ivk-from invowkfile deploy
invowk cmd --ivk-from tools deploy

If you run an ambiguous command without disambiguation, invowk shows an error listing available sources.

tip

You can use @source or --ivk-from even for unique command names to be explicit about where a command comes from.

---

invowk init

Create a new invowkfile in the current directory.

invowk init [flags] [filename]

Optionally pass a custom filename to write.

Flags:

Flag	Short	Description
--force	-f	Overwrite existing invowkfile
--template	-t	Template to use: default, minimal, full

Templates:

• default - A balanced template with a few example commands
• minimal - Bare minimum invowkfile structure
• full - Comprehensive template showing all features

Examples:

# Create a default invowkfile
invowk init

# Create a minimal invowkfile
invowk init --template minimal

# Overwrite existing invowkfile
invowk init --force

---

invowk config

Manage Invowk configuration.

invowk config [command]

Subcommands:

invowk config show

Display current configuration in a readable format.

invowk config show

invowk config dump

Output raw configuration as CUE.

invowk config dump

invowk config path

Show configuration paths (config directory, file, and commands directory).

invowk config path

invowk config init

Create a default configuration file.

invowk config init

invowk config set

Set a configuration value.

invowk config set <key> <value>

Examples:

# Set container engine
invowk config set container_engine podman

# Set default runtime
invowk config set default_runtime virtual

# Set UI options
invowk config set ui.color_scheme dark
invowk config set ui.verbose true
invowk config set ui.interactive false

# Set virtual shell options
invowk config set virtual_shell.enable_uroot_utils true

---

invowk module

Manage invowk modules (self-contained command folders).

Alias

mod is an alias for module. For example, invowk mod list works the same as invowk module list.

invowk module [command]

Subcommands:

invowk module create

Create a new invowk module.

invowk module create <name> [flags]

Flags:

Flag	Short	Description
--path	-p	Parent directory for the module (default: current directory)
--scripts		Create a scripts/ subdirectory
--module-id	-g	Module identifier for invowkmod.cue (default: module name)
--description	-d	Description for invowkmod.cue

Examples:

# Create a module with RDNS naming
invowk module create com.example.mytools

# Override module ID and description
invowk module create mytools --module-id com.example.tools --description "Shared tools"

# Create with scripts directory
invowk module create mytools --scripts

invowk module list

List all discovered modules.

invowk module list

invowk module archive

Create a ZIP archive from a module.

invowk module archive <path> [flags]

Flags:

Flag	Short	Description
--output	-o	Output file path

invowk module import

Import a module from a ZIP file or URL.

invowk module import <source> [flags]

Flags:

Flag	Short	Description
--path	-p	Output directory
--overwrite		Overwrite existing module if present

invowk module add

Resolve a module dependency, update the lock file, and add the requirement to invowkmod.cue.

invowk module add <git-url> <version> [flags]

Flags:

Flag	Description
--alias	Alias for the module namespace
--path	Subdirectory path within the repository

Examples:

invowk module add https://github.com/user/utils.invowkmod.git ^1.0.0
invowk module add git@github.com:user/tools.invowkmod.git ~2.1.0 --alias mytools
invowk module add https://github.com/user/monorepo.git ^1.0.0 --path packages/cli

invowk module remove

Remove a module dependency from both the lock file and invowkmod.cue.

invowk module remove <identifier>

invowk module sync

Sync dependencies from invowkmod.cue.

invowk module sync

invowk module update

Update module dependencies to latest matching versions.

invowk module update [identifier]

invowk module deps

List resolved module dependencies.

invowk module deps

invowk module vendor

Vendor dependencies into invowk_modules/.

invowk module vendor [module-path]

Flags:

Flag	Description
--update	Force re-fetch of all dependencies
--prune	Remove unused vendored modules

note

invowk module vendor resolves dependencies and copies them into invowk_modules/. If invowkmod.lock.cue exists, vendoring uses locked versions by default. Use --update to force re-resolution and --prune to remove stale vendored modules.

---

invowk tui

Interactive terminal UI components for shell scripts.

invowk tui [command] [flags]

tip

TUI components work great in invowkfile scripts! They provide interactive prompts, spinners, file pickers, and more.

Subcommands:

invowk tui input

Prompt for single-line text input.

invowk tui input [flags]

Flags:

Flag	Description
--title	Title for the input prompt
--description	Description below the title
--placeholder	Placeholder text
--value	Initial value
--char-limit	Character limit
--width	Input field width
--password	Hide input (for passwords)
--prompt	Prompt character(s) before input

invowk tui write

Multi-line text editor.

invowk tui write [flags]

Flags:

Flag	Description
--title	Title for the editor
--description	Description below the title
--placeholder	Placeholder text
--value	Initial value
--char-limit	Character limit
--width	Editor width
--height	Editor height
--show-line-numbers	Show line numbers

invowk tui choose

Select from a list of options.

invowk tui choose [options...] [flags]

Flags:

Flag	Description
--title	Title for the selection
--limit	Maximum number of selections (default: 1)
--no-limit	Allow unlimited selections
--height	List height

invowk tui confirm

Prompt for yes/no confirmation.

invowk tui confirm [prompt] [flags]

Flags:

Flag	Description
--title	Title displayed above the prompt
--default	Default to yes when present
--affirmative	Text for "yes" option
--negative	Text for "no" option

invowk tui filter

Fuzzy filter a list of options.

invowk tui filter [options...] [flags]

Options can also be provided via stdin.

Flags:

Flag	Description
--title	Title displayed above the filter
--placeholder	Placeholder text
--width	Filter width
--height	List height
--limit	Maximum selections (default: 1)
--no-limit	Allow unlimited selections
--reverse	Display list in reverse order
--fuzzy	Enable fuzzy matching

invowk tui file

File picker.

invowk tui file [path] [flags]

Flags:

Flag	Description
--title	Title displayed above the picker
--description	Description below the title
--directory	Only show directories
--file	Show files (default: true)
--hidden	Show hidden files
--height	Picker height
--allowed	Allowed file extensions

invowk tui table

Display and select from a table.

invowk tui table [flags]

Reads CSV or TSV data from file or stdin.

Flags:

Flag	Description
--file	CSV file to display
--separator	Column separator (default: ,)
--columns	Column headers (override file header)
--widths	Column widths
--height	Table height
--selectable	Enable row selection

invowk tui spin

Show a spinner while running a command.

invowk tui spin [flags] -- command [args...]

Flags:

Flag	Description
--title	Spinner title
--type	Spinner style

invowk tui pager

Scroll through content.

invowk tui pager [file] [flags]

Reads from file or stdin.

Flags:

Flag	Description
--title	Title displayed above the pager
--line-numbers	Show line numbers
--soft-wrap	Soft wrap long lines

invowk tui format

Format text with markdown, code, emoji, or templates.

invowk tui format [text...] [flags]

Flags:

Flag	Description
--type	Format type: markdown, code, emoji, template
--language	Language for code highlighting
--theme	Glamour theme for code highlighting

invowk tui style

Apply styles to text.

invowk tui style [text...] [flags]

Flags:

Flag	Description
--foreground	Text color (hex or name)
--background	Background color
--bold	Bold text
--italic	Italic text
--underline	Underlined text
--strikethrough	Strikethrough text
--faint	Dimmed text
--blink	Blinking text
--reverse	Reverse colors
--margin-*	Margins (left/right/top/bottom)
--padding-*	Padding (left/right/top/bottom)
--width	Fixed width
--height	Fixed height
--align	Text alignment
--border	Border style: none, normal, rounded, double, thick, hidden

---

invowk validate

Validate invowkfiles, modules, or the entire workspace.

invowk validate [path]

Without arguments, validates the current workspace by running full discovery and reporting all diagnostics from every search path.

With a path argument, auto-detects the target type:

Path	Validation
*.invowkmod directory	Module validation (structure + invowkfile parsing + command tree)
invowkfile.cue file	Invowkfile validation (CUE schema + structural + command tree)
Directory with invowkfile.cue	Invowkfile validation
invowkmod.cue file	Module validation (parent directory)

tip

invowk validate always performs deep validation on modules, including invowkfile parsing and command tree checks.

Examples:

# Validate the entire workspace (discovery + diagnostics)
invowk validate

# Validate a single invowkfile
invowk validate ./invowkfile.cue

# Validate a module (always includes deep validation)
invowk validate ./mymod.invowkmod

# Validate a directory containing an invowkfile
invowk validate ./my-project/

---

invowk completion

Generate shell completion scripts.

invowk completion [shell]

Shells: bash, zsh, fish, powershell

Examples:

# Bash
eval "$(invowk completion bash)"

# Zsh
eval "$(invowk completion zsh)"

# Fish
invowk completion fish > ~/.config/fish/completions/invowk.fish

# PowerShell
invowk completion powershell | Out-String | Invoke-Expression

---

invowk help

Show help for any command.

invowk help [command]

Examples:

invowk help
invowk help cmd
invowk help config set

Exit Codes

Invowk exits with:

• 0 on success
• 1 on CLI or runtime errors
• The wrapped command's exit code when a command or tui spin fails

Error Messages

Invowk provides specific error messages to help diagnose issues:

No Invowkfile Found

When no invowkfile is discovered in any search location:

# No invowkfile found!

We searched for an invowkfile but couldn't find one in the expected locations.

## Search locations (in order of precedence):
1. Current directory (invowkfile and sibling modules)
2. Configured includes (module paths from config)
3. ~/.invowk/cmds/ (modules only)

## Things you can try:
• Create an invowkfile in your current directory:
  $ invowk init

• Or specify a different directory:
  $ cd /path/to/your/project

This message appears when:

• No invowkfile.cue exists in the current directory
• No modules exist in configured includes
• No modules exist in ~/.invowk/cmds/

Solutions:

• Run invowk init to create an invowkfile in the current directory
• Navigate to a directory containing an invowkfile
• Add module paths to your config's includes

Failed to Parse Invowkfile

When an invowkfile is found but contains syntax errors or invalid configuration:

✗ Failed to parse /path/to/invowkfile.cue: invowkfile validation failed:
  #Invowkfile.cmds.0.implementations.0.runtimes.0.name: 3 errors in empty disjunction

# Failed to parse invowkfile!

Your invowkfile contains syntax errors or invalid configuration.

## Common issues:
- Invalid CUE syntax (missing quotes, braces, etc.)
- Unknown field names
- Invalid values for known fields
- Missing required fields (name, script for commands)

## Things you can try:
- Check the error message above for the specific line/column
- Validate your CUE syntax using the cue command-line tool
- Run with verbose mode for more details:
  $ invowk --ivk-verbose cmd

This message appears when:

• CUE syntax errors (missing braces, quotes, etc.)
• Invalid field names or values
• Schema validation failures (e.g., invalid runtime type)
• Missing required fields

Solutions:

• Check the specific error message shown above the help text
• Validate your CUE syntax: cue vet invowkfile.cue
• Run with verbose mode: invowk --ivk-verbose cmd
• Compare against the invowkfile schema reference

tip

The error message always shows the specific parsing error first (e.g., which field failed validation), followed by general troubleshooting guidance.