Metadata-Version: 2.4
Name: tgzr.cli
Version: 0.0.5
Summary: tgzr command line interface
Project-URL: Documentation, https://github.com/open-tgzr/tgzr.cli#readme
Project-URL: Issues, https://github.com/open-tgzr/tgzr.cli/issues
Project-URL: Source, https://github.com/open-tgzr/tgzr.cli
Author-email: Dee <dee.sometech@gmail.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: click
Requires-Dist: rich>=14.2.0
Requires-Dist: uv>=0.9.15
Description-Content-Type: text/markdown

# tgzr.cli
tgzr command line

# Installation

## Standalone Executable

Download the executable corresponding to your platform on https://github.com/open-tgzr/tgzr.cli/releases

## Python Package

Create a virtual environment, activate it, and `pip install -U tgzr.cli`

# Usage

## Config

### Lookup

`tgzr` looks for a config file named `.tgzr` in the current directory. If the config file is not found there
if looks for it in the parent directory and all parent's sub-directories, and goes on up until reaching the
root directory or finding a Config file.

The name of the config file can be specified with the `-n` or `--config-name` option:
- `tgzr -n test-config.tgzr ...`

To start the config lookup in another directory, you can use the `-c` or `--cwd` option:
- `tgzr -c ~/TGZR -n test-config.tgzr ...`

Once the config is found, we refer to its folder as **"home"**.

### Manage

- You can see the config content with:
    - `tgzr config show`
- You can save a config with:
    - `tgzr config save` 
    - This will bake the options into the config, so if you do:
        - `tgzr --verbose config save`
        - Next usage of `tgzr` will behave as if the `--verbose` option was specified.

## Sub Commands

`tgzr` provides different sub-commands depending from where you run it.

A bare `tgzr` (freshly installed or freshly downloaded) will only have `config` and `ws` sub-commands.
The `ws` (short for "workspaces") sub-command will let you create workspaces and install plugins in them.
These plugins will then provide additionnal sub-commands in `tgzr`.

In order to activate a specific list of plugins, you need to run `tgzr` from a workspace. \
All workspaces contain a `tgzr` alias in their root directory (`tgzr.bat` for windows).\
This is the command you want to run in order to use the plugins installed in the workspace.

> __Note__:\
> When running the `tgzr` command from a workspace, the default workspace is always
> the parent workspace.



>__[Not Yet Implemented]__\
> To make this easier, `tgzr` will detect if a current workspace exist
>(or is specified in options) and rerun itself from this workspace.

### Workspaces

- `tgzr ws` has a few sub-commands:
    - `tgzr ws config` : show the general config for the workspaces.
    - `tgzr ws create` : create a new workspace (under the `<home>/workspaces` folder).
    - `tgzr ws ls` : list existing workspaces in current home.
    - `tgzr ws select` : set the default workspaces to operate on (use `--name` to specify the one to select).
    - `tgzr ws show` : show the current workspace config.
    - `tgzr ws switch` : change the default workspaces to operate on.
    - `tgzr ws install` : install packages in the current workspace.

All the commands operating on a workspace will use the current workspace.

You can set a default workspace with `tgzr ws switch` or `tgzr ws select`, or you can specify a workspace by 
name with the `ws -n` / `ws --name` option. 

> **__Note__**:\
>    The `-n` / `--name` options must be specified before the command name:
>    - ⛔ `tgzr ws select --name PROD`
>    - ✅ `tgzr ws -n PROD select`

### Other Commands

use `--help` after the sub-command name to get usage details:

`tgzr <subcommand> --help`

## Env Vars

You can config the session using environement variables.

Use the `tgzr help env` command to list the name of all usable env vars.

The env var name is the config field prepended with the appropriate prefix:
- SessionConfig: `tgzr_<field_name>`
- WorkspacesConfig: `tgzr_ws_<field_name>`
- WorkspaceConfig: `tgzr_ws_default_<field_name>`

You can open the config files saved in the session and workspaces to find 
examples of the env var names.

For example:
- `tgzr_verbose=True tgzr config show` == `tgzr -v config show`
- `tgzr_verbose=False tgzr config show` == `tgzr --quite config show`
- `tgzr_ws_default_workspace_name=MyStudio tgzr ws show` == `tgzr ws --name MyStudio show`

# Plugins

`tgzr` command line is plugin based: all plugin installed in the current virtual env will
be accessible in the command line.

## Implement a Plugin

To implement a plugin you need:
- to declare entry point(s) in a `tgzr.cli.plugin` group.
- to have the entry point(s) lead to a callable accepting one argument: the root click group

__Example__: 
> in `my_package/cli_plugin.py`:
> ```python
> import click
>
> @click.group()
> def my_group():
>     '''My Awesome commands'''
>  
> def install_plugin(group::click.Group):
>     group.add_command(my_group)
> ```
>
> in `pyproject.toml`:
> 
> ```
> [project.entry-points."tgzr.cli.plugin"]
> my_package = "my_package.cli_plugin:install_plugin"
> ```

# Installer

Generate the installer with: `uv run pyinstaller pyinstaller_specs/tgzr-<platform>.spec`
The `tgzr-<platform>` executable will be generated in the `dist/` folder