Packagr Cli

Using Packagr-CLI

Packagr-CLI is still in beta

What is Packagr-CLI?

Packagr-CLI is an open-source, command-line interface designed specifically to work with Packagr

Installation

Packagr CLI can be installed via pip:

pip install packagr-cli

It can then be invoked via the packagr command in any terminal window:

packagr [command] [args]

Quick start

Once you’ve install Packagr-CLI, configure it with the following command, substituting in your own details:

packagr configure <hash-id> chris@packagr.app password

Create a simple hello-world project with this command:

packagr init hello-world

This will create a subfolder called hello-world and a config file called packagr.toml. Let’s add a file called hello.py to the subfolder and add some code

def hello_world(*args, **kwargs):
    return 'Hello, world!'

Finally, we can build and publish our code to Packagr using the following commands:

packagr package
packagr upload

Full list of commands

Configure

packagr configure <hash-id> <email> <password>

You should call the configure command straight after you install Packagr CLI. This command will store your credentials to a config file, packagr_conf.toml, that is referenced by many other of the Packagr CLI commands, and removes the need for the Packagr CLI to contstantly prompt you for your password (as is the case with pip/twine)

Parameters

  • hash-id: Your unique Packagr hash id
  • email: The email address you registered for Packagr with
  • password: The password you registered for Packagr with

Init

packagr init <name> [--overwrite]

In order to create a Package, Packagr needs a file called packagr.toml, which contains information about your package. The package init command creates this file for you

The name argument is optional - if not specified, the name will default to the name of the folder you invoke the call from.

Additionally, the init command will also create a subfolder called name, if one doesn’t already exist. By default, Packagr assumes that the code you want to package is stored in this folder. However, if you want to customize that, you can easily do so by editing the packages parameter in packagr.toml. It’s also possible to modify any of the valuues in the config file manually.

Arguments

  • name (Optional): The name of your package
  • --overwrite (Optional): If you try to run packagr init in a folder where a packagr.toml file already exists, you will be prompted to confirm that you want to overwrite the existing file. Passing this argument overrides the prompt

Set

packagr set <key> <value>

Once your packagr.toml file has been created, you can use the set command to set values within it. For example, if you wanted to add a description to the config, you could enter the following command:

packagr set description "some information"

You could equally just go into your packagr.toml file and add the line description = "some information" manually, but the recommended way is to use the CLI - eventually, the CLI will validate the value of key to ensure that it is valid.

If you enter a duplicate key, you will be prompted to confirm that you want to overwrite it

Arguments

  • key: the setting key
  • value: the setting value

Add

packagr add <key> <value>

The add command works in a similar way to the set command, but it’s purpose is to append data to arrays already defined in the config. For example, if your config already looks like this:

Authors = ['Chris <chris@packagr.app>'] 

Then you can update this value using packagr add Authors "some guy <me@example.com>" to change it to the following:

Authors = [ "Chris <chris@packagr.app>", "Some guy <me@example.com>",]

The add command will also add a value to a key that doesn’t exist.

Arguments

  • key: the setting key
  • value: the setting value

Install

packagr install <some-package>

The install command works in a similar way to pip install - it installs a package using your current environment’s pip installation. However, this command will also look for packages in your Packagr repository, as well as in the public PyPI repository. Once a package is installed correctly, it will also be added to your config’s install_requires section

Arguments

  • packages: a list of packages to install
  • --ignore-errors: In case of multiple packages, passing this argument means that Packagr will continue attempting to install the remaining packages on the list in the case that one fails

Uninstall

packagr uninstall <some-package>

This command does the opposite of install - it uninstalls a given package and removes it from the dependencies list.

Arguments

  • packages: a list of packages to uninstall
  • --ignore-errors: In case of multiple packages, passing this argument means that Packagr will continue attempting to

Bump

packagr bump <version> [--minor] [--major]

The bump command increases the version number of your package. Used without arguments, e.g. packagr bump, it increases the version number, e.g. 1.0.0 becomes 1.0.0. Using the --minor argument increases the minor version number, e.g. 1.0.0 > 1.1.0 and the --major argument converts 1.0.0 to 2.0.0. The --major and --minor arguments can be used in conjuction with each other.

Alternatively, you can use packagr bump 4.5.6 to set the version for a specific value. If you aren’t using semver, which means that the bump command may not be able to parse the existing version number, then you can use this option instead

Arguments

  • version (optional): the version number to set. Not compatible with any other argument
  • --minor (optional): Increase the minor version number
  • --major (optional): Increase the major version number

Package

packagr package

Creates sdist and/or wheel packages based on your config file. Using the command without arguments will create a package in both formats. Using --no-wheel or no-sdist will prevent creation of specific formats

Arguments

  • --no-sdist: Don’t build a tarball
  • --no-wheel: Don’t build a wheel

Upload

packagr upload [--ignore-409]

This command will push your package to Packagr. If you are uploading many packages at once, you may opt to use the --ignore-409 argument, which will skip to the next package if encountering a 409 error (conflict for URL). In future, Packagr CLI will have the ability to display detailed logs from Packagr, which offers a big advantage over twine’s limited ability to handle error responses

Create token

packagr create-token <package> <email> [--write-access]

This command creates an access token for a given package and user. If the --write-access flag is provided, then the created token will have write access.

Delete token

packagr token delete <package> <email>

This command deletes an access token for a given package and user.

Coming soon

The following commands will be added to future versions of Packagr CLI:

  • packagr set-readme <readme-file>: passes the content of a readme file to Description
  • packagr set-public <my-package>: Sets a package as public
  • packagr set-private <my-package>: Sets a package as private