Metadata-Version: 2.4
Name: clicommands
Version: 0.1.1
Summary: Lightweight CLI framework for Python projects with automatic command discovery
Author-email: Octolo <dev@octolo.tech>
License-Expression: MIT
Project-URL: Homepage, https://github.com/octolo/python-clicommands
Project-URL: Repository, https://github.com/octolo/python-clicommands
Project-URL: Documentation, https://github.com/octolo/python-clicommands#readme
Project-URL: Issues, https://github.com/octolo/python-clicommands/issues
Keywords: client,command,shell
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tabulate>=0.9.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# clicommands

Lightweight Python library for managing command-line commands with automatic discovery.

## Features

- **Automatic command discovery** via `commands/` directory or `.commands.json`
- **Two ways to define commands**: function suffixed with `_command` or `Command` class
- **Argument parsing API**: `classify_args`, `parse_args_from_config`
- **Envfile loading**: `ENVFILE_PATH` support for loading `.env`
- **Built-in commands**: `version`, `copy`, `varenv`

## Installation

```bash
pip install clicommands
```

## Quick Start

1. Create a `cli.py` in your package:

```python
import sys
from pathlib import Path
from clicommands.helpers import cli_main

def main(argv=None):
    cli_file_path = Path(__file__)
    result = cli_main(cli_file_path, argv)
    return int(result) if isinstance(result, (int, bool)) else (0 if result else 1)

if __name__ == "__main__":
    sys.exit(main())
```

2. Add a `commands/` directory with your commands:

```python
# commands/hello.py
def hello_command(args: list[str]) -> bool:
    """Say hello."""
    print("Hello, world!")
    return True
```

3. Run: `python -m mypackage.cli hello`

## .commands.json Configuration

```json
{
  "packages": ["other_package"],
  "directories": ["commands"],
  "commands": []
}
```

- `packages`: Packages to import commands from
- `directories`: Paths to command directories
- `commands`: Additional commands

## Documentation

- `docs/purpose.md` — Purpose and use cases
- `docs/structure.md` — Project organization
- `docs/development.md` — Development guidelines
- `docs/AI.md` — AI assistant contract
