import "../autodoc.css"

# CLI helpers

Most applications only need [`@proto.cli`](/reference/configuration#params_proto.proto--cli). These lower-level functions support custom command-line parsing and help rendering.

```python
from params_proto.cli import parse_cli_args, colorize_help, get_terminal_width
```

`parse_cli_args` consumes a decorated wrapper; it is not a general argument-list parser. For everyday usage, follow [CLI applications](/examples/cli_applications).

## API index

| Name | Kind | Defined in |
| --- | --- | --- |
| [`Colors`](/reference/cli#params_proto.cli.ansi_help--colors) | class | `params_proto.cli.ansi_help` |
| [`get_terminal_width`](/reference/cli#params_proto.cli.ansi_help--get_terminal_width) | function | `params_proto.cli.ansi_help` |
| [`strip_ansi`](/reference/cli#params_proto.cli.ansi_help--strip_ansi) | function | `params_proto.cli.ansi_help` |
| [`wrap_text_with_ansi`](/reference/cli#params_proto.cli.ansi_help--wrap_text_with_ansi) | function | `params_proto.cli.ansi_help` |
| [`colorize_help`](/reference/cli#params_proto.cli.ansi_help--colorize_help) | function | `params_proto.cli.ansi_help` |
| [`get_ansi_help`](/reference/cli#params_proto.cli.ansi_help--get_ansi_help) | function | `params_proto.cli.ansi_help` |
| [`parse_cli_args`](/reference/cli#params_proto.cli.cli_parse--parse_cli_args) | function | `params_proto.cli.cli_parse` |

<a id="params_proto.cli" />

## params_proto.cli

CLI argument parsing and help generation for params-proto.

This module handles:
- Command-line argument parsing
- Help text generation
- ANSI colorization for terminal output

<a id="params_proto.cli--public-imports" />

### Public imports

These symbols are available from this module. Their definitions are documented in the linked modules.

- [`parse_cli_args`](/reference/cli#params_proto.cli.cli_parse--parse_cli_args) — `params_proto.cli.cli_parse.parse_cli_args`
- [`colorize_help`](/reference/cli#params_proto.cli.ansi_help--colorize_help) — `params_proto.cli.ansi_help.colorize_help`
- [`get_terminal_width`](/reference/cli#params_proto.cli.ansi_help--get_terminal_width) — `params_proto.cli.ansi_help.get_terminal_width`
<a id="params_proto.cli.ansi_help" />

## params_proto.cli.ansi_help

ANSI-formatted help text generation for terminal display.

Provides colorized, terminal-width-aware formatting of help text.
Keeps __help_str__ as plain text for testing, adds __ansi_str__ for display.

Terminal Detection Notes:
------------------------

Width Detection:
  - Uses shutil.get_terminal_size() which queries terminal dimensions
  - Checks COLUMNS env var first, then terminal ioctl
  - Width can change during a session (user resizes window)
  - For params-proto: No caching needed since help is printed once and exits
  - For long-running CLIs: Would need SIGWINCH handler or query-per-print
  - Current approach (query on each colorize_help() call) is correct and cheap

Color Detection:
  - Currently NOT implemented - colors always applied
  - Should check:
    * sys.stdout.isatty() - False for pipes/redirects
    * NO_COLOR env var - https://no-color.org/
    * TERM env var - 'dumb' or missing means no color support
  - TODO: Add should_use_color() function

Performance:
  - shutil.get_terminal_size() is fast (just reads terminal attributes)
  - No need to cache width since help is only printed once per execution
  - For high-frequency printing, would consider caching with SIGWINCH handler

<a id="params_proto.cli.ansi_help--colors" />

### `Colors`

<section className="py-api">
<div className="py-api-header">
<span className="py-api-kind">class</span>
<code className="py-api-name">params&#95;proto.cli.ansi&#95;help.Colors</code>
<a className="py-api-source" href="https://github.com/dreamlake-ai/params-proto/blob/v3.3.0/src/params_proto/cli/ansi_help.py#L39">Source ↗</a>
</div>
<pre className="py-api-signature"><code>class Colors</code></pre>
<div className="py-api-description">

ANSI color codes for terminal formatting.

<p className="py-api-section-label">Attributes</p>
<table className="py-api-fields">
<thead><tr><th>Name</th><th>Type / value</th><th>Description</th></tr></thead>
<tbody>
<tr><td><a id="params_proto.cli.ansi_help--colors.reset" /><code>RESET</code></td><td><code>&#x27;\x1b[0m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.bold" /><code>BOLD</code></td><td><code>&#x27;\x1b[1m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.dim" /><code>DIM</code></td><td><code>&#x27;\x1b[2m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.red" /><code>RED</code></td><td><code>&#x27;\x1b[31m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.green" /><code>GREEN</code></td><td><code>&#x27;\x1b[32m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.yellow" /><code>YELLOW</code></td><td><code>&#x27;\x1b[33m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.blue" /><code>BLUE</code></td><td><code>&#x27;\x1b[34m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.magenta" /><code>MAGENTA</code></td><td><code>&#x27;\x1b[35m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.cyan" /><code>CYAN</code></td><td><code>&#x27;\x1b[36m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.white" /><code>WHITE</code></td><td><code>&#x27;\x1b[37m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.bright&#95;black" /><code>BRIGHT&#95;BLACK</code></td><td><code>&#x27;\x1b[90m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.bright&#95;red" /><code>BRIGHT&#95;RED</code></td><td><code>&#x27;\x1b[91m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.bright&#95;green" /><code>BRIGHT&#95;GREEN</code></td><td><code>&#x27;\x1b[92m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.bright&#95;yellow" /><code>BRIGHT&#95;YELLOW</code></td><td><code>&#x27;\x1b[93m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.bright&#95;blue" /><code>BRIGHT&#95;BLUE</code></td><td><code>&#x27;\x1b[94m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.bright&#95;magenta" /><code>BRIGHT&#95;MAGENTA</code></td><td><code>&#x27;\x1b[95m&#x27;</code></td><td>—</td></tr>
<tr><td><a id="params_proto.cli.ansi_help--colors.bright&#95;cyan" /><code>BRIGHT&#95;CYAN</code></td><td><code>&#x27;\x1b[96m&#x27;</code></td><td>—</td></tr>
</tbody>
</table>

</div>
</section>

<a id="params_proto.cli.ansi_help--get_terminal_width" />

### `get_terminal_width`

<section className="py-api">
<div className="py-api-header">
<span className="py-api-kind">function</span>
<code className="py-api-name">params&#95;proto.cli.ansi&#95;help.get&#95;terminal&#95;width</code>
<a className="py-api-source" href="https://github.com/dreamlake-ai/params-proto/blob/v3.3.0/src/params_proto/cli/ansi_help.py#L68">Source ↗</a>
</div>
<pre className="py-api-signature"><code>get&#95;terminal&#95;width(<span className="py-api-param">default</span>: <span className="py-api-type">int</span> = <span className="py-api-default">80</span>, <span className="py-api-param">max&#95;width</span>: <span className="py-api-type">int</span> = <span className="py-api-default">120</span>) → <span className="py-api-type">int</span></code></pre>
<div className="py-api-description">

Get the current terminal width.

<p className="py-api-section-label">Parameters</p>
<table className="py-api-fields">
<thead><tr><th>Parameter</th><th>Type / default</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>default</code></td><td><code><span className="py-api-type">int</span></code><br /><span className="py-api-default"> = 80</span></td><td>Default width if terminal size cannot be detected</td></tr>
<tr><td><code>max&#95;width</code></td><td><code><span className="py-api-type">int</span></code><br /><span className="py-api-default"> = 120</span></td><td>Maximum width to use even if terminal is wider</td></tr>
</tbody>
</table>

<p className="py-api-section-label">Returns</p>
<p><code><span className="py-api-type">int</span></code> — Terminal width in characters</p>

</div>
</section>

<a id="params_proto.cli.ansi_help--strip_ansi" />

### `strip_ansi`

<section className="py-api">
<div className="py-api-header">
<span className="py-api-kind">function</span>
<code className="py-api-name">params&#95;proto.cli.ansi&#95;help.strip&#95;ansi</code>
<a className="py-api-source" href="https://github.com/dreamlake-ai/params-proto/blob/v3.3.0/src/params_proto/cli/ansi_help.py#L87">Source ↗</a>
</div>
<pre className="py-api-signature"><code>strip&#95;ansi(<span className="py-api-param">text</span>: <span className="py-api-type">str</span>) → <span className="py-api-type">str</span></code></pre>
<div className="py-api-description">

Remove ANSI escape codes from text.

<p className="py-api-section-label">Parameters</p>
<table className="py-api-fields">
<thead><tr><th>Parameter</th><th>Type / default</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>text</code></td><td><code><span className="py-api-type">str</span></code><br /><span className="py-api-default">required</span></td><td>Text potentially containing ANSI codes</td></tr>
</tbody>
</table>

<p className="py-api-section-label">Returns</p>
<p><code><span className="py-api-type">str</span></code> — Plain text with ANSI codes removed</p>

</div>
</section>

<a id="params_proto.cli.ansi_help--wrap_text_with_ansi" />

### `wrap_text_with_ansi`

<section className="py-api">
<div className="py-api-header">
<span className="py-api-kind">function</span>
<code className="py-api-name">params&#95;proto.cli.ansi&#95;help.wrap&#95;text&#95;with&#95;ansi</code>
<a className="py-api-source" href="https://github.com/dreamlake-ai/params-proto/blob/v3.3.0/src/params_proto/cli/ansi_help.py#L100">Source ↗</a>
</div>
<pre className="py-api-signature"><code>wrap&#95;text&#95;with&#95;ansi(<span className="py-api-param">text</span>: <span className="py-api-type">str</span>, <span className="py-api-param">width</span>: <span className="py-api-type">int</span>, <span className="py-api-param">indent</span>: <span className="py-api-type">str</span> = <span className="py-api-default">&#x27;&#x27;</span>) → <span className="py-api-type">list</span></code></pre>
<div className="py-api-description">

Wrap text while preserving ANSI codes.

<p className="py-api-section-label">Parameters</p>
<table className="py-api-fields">
<thead><tr><th>Parameter</th><th>Type / default</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>text</code></td><td><code><span className="py-api-type">str</span></code><br /><span className="py-api-default">required</span></td><td>Text to wrap (may contain ANSI codes)</td></tr>
<tr><td><code>width</code></td><td><code><span className="py-api-type">int</span></code><br /><span className="py-api-default">required</span></td><td>Target width for wrapping</td></tr>
<tr><td><code>indent</code></td><td><code><span className="py-api-type">str</span></code><br /><span className="py-api-default"> = &#x27;&#x27;</span></td><td>Indentation string for wrapped lines</td></tr>
</tbody>
</table>

<p className="py-api-section-label">Returns</p>
<p><code><span className="py-api-type">list</span></code> — List of wrapped lines</p>

</div>
</section>

<a id="params_proto.cli.ansi_help--colorize_help" />

### `colorize_help`

<section className="py-api">
<div className="py-api-header">
<span className="py-api-kind">function</span>
<code className="py-api-name">params&#95;proto.cli.ansi&#95;help.colorize&#95;help</code>
<a className="py-api-source" href="https://github.com/dreamlake-ai/params-proto/blob/v3.3.0/src/params_proto/cli/ansi_help.py#L140">Source ↗</a>
</div>
<pre className="py-api-signature"><code>colorize&#95;help(<span className="py-api-param">help&#95;str</span>: <span className="py-api-type">str</span>, <span className="py-api-param">width</span>: <span className="py-api-type">Optional</span>[<span className="py-api-type">int</span>] = <span className="py-api-default">None</span>) → <span className="py-api-type">str</span></code></pre>
<div className="py-api-description">

Add ANSI colors and line wrapping to help text.

Colorization:
- Type names (INT, STR, FLOAT, etc.) -&gt; bold bright blue ()
- (required) -&gt; bold red ()
- (default: value) -&gt; cyan parentheses with bold cyan value
  Example: (default: 128)
- Option names (--foo) -&gt; plain text (no formatting)

<p className="py-api-section-label">Parameters</p>
<table className="py-api-fields">
<thead><tr><th>Parameter</th><th>Type / default</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>help&#95;str</code></td><td><code><span className="py-api-type">str</span></code><br /><span className="py-api-default">required</span></td><td>Plain text help string</td></tr>
<tr><td><code>width</code></td><td><code><span className="py-api-type">Optional</span>[<span className="py-api-type">int</span>]</code><br /><span className="py-api-default"> = None</span></td><td>Terminal width (auto-detected if None)</td></tr>
</tbody>
</table>

<p className="py-api-section-label">Returns</p>
<p><code><span className="py-api-type">str</span></code> — ANSI-formatted help text with proper line wrapping</p>

</div>
</section>

<a id="params_proto.cli.ansi_help--get_ansi_help" />

### `get_ansi_help`

<section className="py-api">
<div className="py-api-header">
<span className="py-api-kind">function</span>
<code className="py-api-name">params&#95;proto.cli.ansi&#95;help.get&#95;ansi&#95;help</code>
<a className="py-api-source" href="https://github.com/dreamlake-ai/params-proto/blob/v3.3.0/src/params_proto/cli/ansi_help.py#L361">Source ↗</a>
</div>
<pre className="py-api-signature"><code>get&#95;ansi&#95;help(<span className="py-api-param">wrapper</span>) → <span className="py-api-type">str</span></code></pre>
<div className="py-api-description">

Get ANSI-formatted help string from a proto wrapper.

<p className="py-api-section-label">Parameters</p>
<table className="py-api-fields">
<thead><tr><th>Parameter</th><th>Type / default</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>wrapper</code></td><td><code>—</code><br /><span className="py-api-default">required</span></td><td>ProtoWrapper instance with &#95;&#95;help&#95;str&#95;&#95;</td></tr>
</tbody>
</table>

<p className="py-api-section-label">Returns</p>
<p><code><span className="py-api-type">str</span></code> — ANSI-formatted help text</p>

</div>
</section>
<a id="params_proto.cli.cli_parse" />

## params_proto.cli.cli_parse

CLI argument parsing for params-proto v3.

Converts sys.argv into kwargs for proto-decorated functions.
Simple custom parser - no argparse dependency.

<a id="params_proto.cli.cli_parse--parse_cli_args" />

### `parse_cli_args`

<section className="py-api">
<div className="py-api-header">
<span className="py-api-kind">function</span>
<code className="py-api-name">params&#95;proto.cli.cli&#95;parse.parse&#95;cli&#95;args</code>
<a className="py-api-source" href="https://github.com/dreamlake-ai/params-proto/blob/v3.3.0/src/params_proto/cli/cli_parse.py#L212">Source ↗</a>
</div>
<pre className="py-api-signature"><code>parse&#95;cli&#95;args(<span className="py-api-param">wrapper</span>) → <span className="py-api-type">Dict</span>[<span className="py-api-type">str</span>, <span className="py-api-type">Any</span>]</code></pre>
<div className="py-api-description">

Parse CLI arguments for a ProtoWrapper.

<p className="py-api-section-label">Parameters</p>
<table className="py-api-fields">
<thead><tr><th>Parameter</th><th>Type / default</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>wrapper</code></td><td><code>—</code><br /><span className="py-api-default">required</span></td><td>ProtoWrapper instance</td></tr>
</tbody>
</table>

<p className="py-api-section-label">Returns</p>
<p><code><span className="py-api-type">Dict</span>[<span className="py-api-type">str</span>, <span className="py-api-type">Any</span>]</code> — Dictionary of parsed arguments</p>

</div>
</section>