How to Use the `soup version` Command in the Soup CLI

The soup version command queries the __version__ constant defined in src/soup_cli/__init__.py and renders the package version string through the Rich console interface.

The soup version command is a core utility shipped with the Soup CLI toolchain maintained in the MakazhanAlpamys/Soup repository. When you need to verify which release is installed in a virtual environment or container, this command provides the authoritative version identifier. Understanding how to invoke and parse this command ensures your pipelines and local development environments remain synchronized with the correct release.

What the soup version Command Does

According to the MakazhanAlpamys/Soup source code, the version subcommand retrieves the package version and prints it to stdout. The function utilizes the Rich library to format the output, providing colored text that distinguishes the tool name from the version number. This approach ensures human-readable results in interactive terminals while remaining parseable by shell scripts.

Command Syntax and Usage

The soup version command supports multiple invocation patterns depending on your installation method.

Standard CLI Invocation

When the package is installed in your environment, call the command directly:

soup version

This executes the version function in src/soup_cli/cli.py and prints the formatted version string to stdout.

Module Execution

If the soup executable is not available on your system PATH, invoke the module directly:

python -m soup_cli version

This entry point loads the same implementation from src/soup_cli/cli.py, ensuring consistent output across different execution contexts.

Source Code Implementation

The command logic resides in two key files within the repository structure.

In src/soup_cli/cli.py (around line 607), the version function retrieves and displays the package version:

# Located in src/soup_cli/cli.py

def version():
    console.print(f"Soup CLI version {__version__}")

In src/soup_cli/__init__.py, the __version__ constant defines the release identifier used by the command:

__version__ = "0.3.1"

This architecture ensures the version string is maintainable in one location while remaining accessible to both the CLI and Python API consumers.

Practical Code Examples

Verify your installation in a deployment script:

# Check version before running migrations

INSTALLED_VERSION=$(soup version | awk '{print $NF}')
if [ "$INSTALLED_VERSION" != "0.3.1" ]; then
    echo "Version mismatch detected"
    exit 1
fi

Access the version programmatically without spawning a subprocess:

from soup_cli import __version__

print(f"Running Soup version {__version__}")

Summary

• The soup version command reads the __version__ constant from src/soup_cli/__init__.py.
• Implementation resides in src/soup_cli/cli.py and uses Rich for terminal formatting.
• Invoke via soup version or python -m soup_cli version depending on your environment.
• The command returns exit code 0 and requires no arguments.
• Programmatic access is available by importing __version__ directly from the soup_cli package.

Frequently Asked Questions

What information does the soup version command display?

The command outputs a single line containing the string "Soup CLI version" followed by the semantic version number. The Rich library applies color formatting to distinguish the label from the version string in terminal environments.

Where is the version number defined in the source code?

The version string is defined as __version__ in src/soup_cli/__init__.py. The CLI command in src/soup_cli/cli.py imports this constant and passes it to the console printer.

Can I use soup version in automation scripts?

Yes. Because the command writes to stdout and exits with code 0, you can capture its output in shell scripts using command substitution. For Python automation, importing __version__ directly from soup_cli avoids subprocess overhead.

How does the command handle output formatting?

The implementation uses the Rich Console class to render the version string. This provides automatic colorization when outputting to a terminal while ensuring plain text is emitted when the output is piped to files or other processes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}