CLI Reference

There are two categories of pib_cli commands:

internal commands
customizable commands

While the internal commands are statically defined, you have complete control over the customizable commands.

pib_cli ships with some default customized commands that you can use with your project right away.

PIB CLI Internal Commands

These commands allow you to interact with the pib_cli application itself:

dev @pib

PIB built-in commands.

dev @pib [OPTIONS] COMMAND [ARGS]...

config

PIB CLI configuration commands.

dev @pib config [OPTIONS] COMMAND [ARGS]...

Options

-c, --config-file <config_file>: A config file to use instead of the active one.

show

Display a CLI configuration file (defaults to the active file).

dev @pib config show [OPTIONS]

validate

Validate a CLI configuration file (defaults to the active file).

dev @pib config validate [OPTIONS]

version

Find a CLI configuration file’s version (defaults to the active file).

dev @pib config version [OPTIONS]

where

Locate a CLI configuration file (defaults to the active file).

dev @pib config where [OPTIONS]

container

PIB container commands.

dev @pib container [OPTIONS] COMMAND [ARGS]...

setup

Copy file assets to setup the development container.

dev @pib container setup [OPTIONS]

validate

Validate the current container is compatible with the CLI.

dev @pib container validate [OPTIONS]

version

Display the current container version.

dev @pib container version [OPTIONS]

version

Display the current CLI version.

dev @pib version [OPTIONS]

PIB CLI Default Custom Commands

These are the default configuration based commands shipped with pib_cli:

dev

Click group of all custom defined commands.

dev [OPTIONS] COMMAND [ARGS]...

build-wheel

Build a distribution wheel.

dev build-wheel [OPTIONS] [ARGS]...

Arguments

ARGS: Optional argument(s)

coverage

Run code coverage test.

dev coverage [OPTIONS] [ARGS]...

Arguments

ARGS: Optional argument(s)

fmt

Run code formatters.

dev fmt [OPTIONS] [ARGS]...

Arguments

ARGS: Optional argument(s)

lint

Run the code linters.

dev lint [OPTIONS] [ARGS]...

Arguments

ARGS: Optional argument(s)

reinstall-requirements

Reinstall the project requirements.

dev reinstall-requirements [OPTIONS] [ARGS]...

Arguments

ARGS: Optional argument(s)

sectest

Run the security tests.

dev sectest [OPTIONS] [ARGS]...

Arguments

ARGS: Optional argument(s)

test

Run the unittests.

dev test [OPTIONS] [ARGS]...

Arguments

ARGS: Optional argument(s)

PIB CLI Default Configuration

The default YAML CLI configuration:

# The default PIB CLI configuration.
---
cli_definition:
  - name: "build-wheel"
    description: "Build a distribution wheel."
    path: "repo_root"
    commands:
      - "poetry build"
    success: "Wheel Built"
    failure: "Error Building Wheel"
  - name: "coverage"
    description: "Run code coverage test."
    path: "repo_root"
    commands:
      - 'pytest --cov-report term-missing --cov-report html --cov-fail-under=100 --cov="${PIB_PROJECT_NAME}" "${PIB_PROJECT_NAME}/" ${PIB_OVERLOAD_ARGUMENTS}'
    success: "Coverage Passed!"
    failure: "Coverage Failed!"
  - name: "fmt"
    description: "Run code formatters."
    path: "repo_root"
    commands:
      - 'yapf -i --recursive .'
      - 'isort "${PIB_PROJECT_NAME}"'
    success: "Formatting Finished!"
    failure: "Formatting Error!"
  - name: "lint"
    path: "repo_root"
    description: "Run the code linters."
    commands:
      - 'yamllint .'
      - 'isort -c "${PIB_PROJECT_NAME}"'
      - 'pytest --pylint --pylint-jobs=2 "${PIB_PROJECT_NAME}"'
    success: "Linter Test Passed!"
    failure: "Linter Test Failed!"
  - name: "reinstall-requirements"
    description: "Reinstall the project requirements."
    path: "repo_root"
    commands:
      - "poetry lock"
      - "poetry install"
    success: "Reinstall Succeeded!"
    failure: "Reinstall Failed!"
  - name: "sectest"
    description: "Run the security tests."
    path: "repo_root"
    commands:
      - 'bandit -r "${PIB_PROJECT_NAME}" -x tests'
      - 'echo "\nPoetry is exporting the lockfile standby..."'
      - 'poetry export --without-hashes -f requirements.txt | safety check --stdin'
    success: "Security Test Passed!"
    failure: "Security Test Failed!"
  - name: "test"
    description: "Run the unittests."
    path: "repo_root"
    commands:
      - 'pytest ${PIB_OVERLOAD_ARGUMENTS}'
    success: "Unittests Passed!"
    failure: "Unittests Failed!"

PIB CLI Configuration JSON Schema

Follow this schema to build your own CLI commands:

PIB CLI Base Configuration Specification v2.1.0

The specification for the PIB CLI user configuration file.
type	object
properties
metadata	type	object
	properties
	project_name	The name of the project being managed by PIB.
		type	string
		pattern	[0-9a-zA-Z-_]+$
	documentation_root	The relative path from the repository root to the Sphinx Makefile folder.
		type	string
		pattern	[\s0-9a-zA-Z-_/\\]+$
	additionalProperties	False
cli_definition	PIB CLI Custom Command Configuration Specification v0.1.0
additionalProperties	False

PIB CLI Custom Command Configuration Specification v0.1.0

The specification for user defined CLI commands.
type	array
items	type	object
	properties
	name	The CLI command name. (‘@pib’ is a reserved command name and cannot be redefined.)
		type	string
		pattern	^(?!@pib$)[0-9a-zA-Z-_]+$
	description	A description of the CLI command. (Appears in CLI help messages.)
		type	string
	path	The filesystem location from which to execute the command.
		enum	documentation_root, git_root, project_root, repo_root
	commands	The shell commands that will be run.
		type	string / array
		items	An individual shell command.
			type	string
		minItems	1
	success	A message to display on success.
		type	string
	failure	A message to display on failure.
		type	string
	container_only	Restrict this command to inside a managed PIB container.
		type	boolean
	additionalProperties	False
uniqueItems	True