Ginx Commands

Reference for all Ginx commands.

Script Execution Commands

The core of Ginx is running your project scripts. There are two ways to execute scripts, and understanding when to use each makes you more effective.

Direct Script Commands (Recommended)

ginx <script-name>              # Run any script directly
ginx format                     # Run format script
ginx build --verbose            # Run with verbose output
ginx test --dry-run             # See what would run without executing
ginx deploy "v1.2.3"            # Pass arguments to script

Why use direct commands? This is Ginx's main innovation - turning ginx run format into just ginx format. It's faster to type and feels more natural, like the script is a built-in command.

How it works: Ginx dynamically registers each script in your ginx.yaml as a command when you run ginx. This means ginx format is functionally identical to having a standalone format CLI tool.

Run Command (Fallback)

ginx run <script-name>          # Alternative to direct execution
ginx run format                 # Same as 'ginx format'
ginx run build --stream         # Enable output streaming this is default set
ginx run build --no-stream      # This will execute your command quite and dump the results after completion

When to use run: Only when your script name conflicts with a built-in Ginx command (like if you named a script list or version). Otherwise, prefer direct commands.

Execution Options

All script execution commands support these options:

--dry-run, -n                   # Show what would execute without running
--verbose, -v                   # Show detailed execution info  
--stream/--no-stream            # Control real-time output (default: enabled)

--dry-run is your safety net. Always use it first with unfamiliar or potentially dangerous scripts:

ginx deploy --dry-run           # See what deploy would do
ginx deploy                     # Actually deploy after verification

--verbose shows the full context - script description, working directory, environment variables, and shell mode. Essential for debugging:

ginx build --verbose
# Output:
# Script: build
# Description: Build source and wheel distributions
# Working directory: current
# Shell mode: Yes
# Running: python -m build

--stream controls output display. Enabled by default so you see command output in real-time. Disable for cleaner logs:

ginx test --no-stream           # Capture all output, show at end

Project Management Commands

These commands help you set up and maintain your Ginx configuration.

ginx init                       # Create sample ginx.yaml
ginx init --force               # Overwrite existing file with a default ginx init file

ginx init is your starting point for any new project. It creates a complete ginx.yaml with common patterns you can customize.

Validate Configuration

ginx validate                   # Check ginx.yaml for errors

Run this after editing your configuration. It catches common issues like missing command fields or malformed YAML before you try to run scripts.

Dependencies

Check Dependencies

ginx deps                       # Check script dependencies

Verifies all tools referenced in your scripts are available. Ginx extracts command names from your scripts (like pytest, black, docker) and checks if they're installed.

Shows missing dependencies and suggests installation commands:

Found requirements files:
  requirements.txt: 45 packages

Script dependencies:
  ✓ mypy
  ✓ flake8
  ✓ ginx
  ✓ isort
  ✗ black
  ✗ pytest

Missing commands:
  - black
  - pytest

Debugging & Info Commands

When things go wrong, these commands help you understand what's happening.

Version Info

ginx version                    # Show Ginx version

Always include this in bug reports. Different Ginx versions have different features and behaviours.

Debug Plugins

ginx debug-plugins              # Show plugin loading status

Use when plugins aren't working as expected. Shows which plugins are registered, their versions, and any loading errors.

Exit Codes & Scripting

Ginx returns meaningful exit codes for scripting integration:

• 0 - Success

• 1 - General error (script not found, validation failed)

• 124 - Command timeout

• 130 - Interrupted by user (Ctrl+C)

• Other - The exit code of the failed script

This command reference gives you both the what and the why of every Ginx command. Use it as both a learning tool and a quick lookup reference.