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
--interactive	-i	Run commands in alternate screen buffer (interactive mode)
--verbose	-v	Enable verbose output
--version		Show version information

Commands

invowk

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

invowk [flags]
invowk [command]

---

invowk cmd

Execute commands defined in invkfiles.

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

Flags:

Flag	Short	Description
--list	-l	List all available commands
--runtime	-r	Override the runtime (must be allowed by the command)
--from		Source to run command from (e.g., 'invkfile' or module name)

Built-in per-command flags:

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

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 --invk-runtime container

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

# Run with flags
invowk cmd deploy --env production

Command Discovery:

Commands are discovered from (in priority order):

1. Current directory (invkfile and modules)
2. ~/.invowk/cmds/ (invkfiles and modules)
3. Paths configured in search_paths (invkfiles and modules)

Command Disambiguation:

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

Using @source prefix:

invowk cmd @invkfile deploy      # Run deploy from invkfile
invowk cmd @tools deploy         # Run deploy from tools.invkmod
invowk cmd @tools.invkmod deploy # Full module name also works

Using --from flag:

invowk cmd --from invkfile deploy
invowk cmd --from tools deploy

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

tip

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

---

invowk init

Create a new invkfile in the current directory.

invowk init [flags] [path]

Optionally pass a custom filename to write.

Flags:

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

Templates:

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

Examples:

# Create a default invkfile
invowk init

# Create a minimal invkfile
invowk init --template minimal

# Overwrite existing invkfile
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 the configuration file path.

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 nested value
invowk config set ui.color_scheme dark

---

invowk module

Manage invowk modules (self-contained command folders).

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 invkmod.cue (default: module name)
--description	-d	Description for invkmod.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 validate

Validate an invowk module.

invowk module validate <path> [flags]

Flags:

Flag	Short	Description
--deep		Also validate invkfile syntax

Examples:

# Basic validation
invowk module validate ./mymod.invkmod

# Deep validation
invowk module validate ./mymod.invkmod --deep

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 alias

Manage module aliases for collision disambiguation.

invowk module alias [command]

invowk module alias set

invowk module alias set <module-path> <alias>

invowk module alias list

invowk module alias list

invowk module alias remove

invowk module alias remove <module-path>

invowk module add

Resolve a module dependency and print the requires entry for invkmod.cue.

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

Flags:

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

invowk module remove

Remove a module dependency from the lock file.

invowk module remove <git-url>

invowk module sync

Sync dependencies from invkmod.cue.

invowk module sync

invowk module update

Update module dependencies to latest matching versions.

invowk module update [git-url]

invowk module deps

List resolved module dependencies.

invowk module deps

invowk module vendor

Vendor dependencies into invk_modules/.

invowk module vendor [module-path]

Flags:

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

---

invowk tui

Interactive terminal UI components for shell scripts.

invowk tui [command] [flags]

tip

TUI components work great in invkfile 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 value (true/false)
--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	Only show files
--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

---

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 Invkfile Found

When no invkfile is discovered in any search location:

# No invkfile found!

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

## Search locations (in order of precedence):
1. Current directory
2. ~/.invowk/cmds/
3. Paths configured in your config file

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

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

This message appears when:

• No invkfile.cue exists in the current directory
• No invkfiles exist in ~/.invowk/cmds/
• No invkfiles exist in configured search_paths

Solutions:

• Run invowk init to create an invkfile in the current directory
• Navigate to a directory containing an invkfile
• Add invkfile locations to your config's search_paths

Failed to Parse Invkfile

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

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

# Failed to parse invkfile!

Your invkfile 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 --invk-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 invkfile.cue
• Run with verbose mode: invowk --verbose cmd --list
• Compare against the invkfile schema reference

tip

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