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

> Learn how to use the soup version command to check your Soup CLI package version. This simple command displays the current version through the Rich console interface.

- Repository: [Alpamys Makazhan/Soup](https://github.com/MakazhanAlpamys/Soup)
- Tags: how-to-guide
- Published: 2026-09-06

---

**The `soup version` command queries the `__version__` constant defined in [`src/soup_cli/__init__.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/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:

```bash
soup version

```

This executes the `version` function in [`src/soup_cli/cli.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/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:

```bash
python -m soup_cli version

```

This entry point loads the same implementation from [`src/soup_cli/cli.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/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`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/cli.py)** (around line 607), the `version` function retrieves and displays the package version:

```python

# Located in src/soup_cli/cli.py

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

```

**In [`src/soup_cli/__init__.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/__init__.py)**, the `__version__` constant defines the release identifier used by the command:

```python
__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:

```bash

# 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:

```python
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`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/__init__.py).
- Implementation resides in [`src/soup_cli/cli.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/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`](https://github.com/MakazhanAlpamys/Soup/blob/main/src/soup_cli/__init__.py). The CLI command in [`src/soup_cli/cli.py`](https://github.com/MakazhanAlpamys/Soup/blob/main/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.