tgzr.cli 0.0.3

tgzr command line interface

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:

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"