CLI client for alwaysdata customers operations purposes.

The project relies on Python 3.11 and Nuitka for its build / distribution process. It uses Poetry and PoeThePoet to ensure the development workflow.

For local build purposes, you'll also need patchelf, clang, and upx.

1. Check that Poetry is properly installed and install it otherwise:

   $ which poetry || curl -sSL https://install.python-poetry.org | python3 -

2. Install dependencies:

   $ poetry self add 'poethepoet[poetry_plugin]'
   $ poetry install

Poetry declares an alwaysdata command that runs the __main__ script. The name is choosen after the expacted name of the CLI when distributed.

To run the CLI, call it with Poetry:

$ poetry run alwaysdata --help

Top-level tasks are handled with PoeThePoet in the pyproject.toml file, under the package name (alcli) as top-level command. You can run:

$ poetry alcli format   # format source and test files
$ poetry alcli test     # run tests
$ poetry alcli build    # build a distributable asset

Run the poetry alcli command for an exhaustive list of supported commands.

The project heavily relies on Typer as its "frontend" framework for CLI commands.

The main command, as well as the Typer app instance, lives in the src/alcli.py file.

Every sub-commands (config, auth, site, etc.) are dedicated Typer sub-apps commands living in their dedicated modules in src.

The src/utils package contains useful wrapper for api calls or console printing, as we allow users to select the kind of feedback they want on stdout (json or plain-text, with or without theming, etc). Subcommands must rely on those utils to enforce a consistent user experience at last.

We'll add a new my module which will exposes a endpoint sub-command, returning an arbitrary endpoint (namely my-endpoint) at the API.

Add a new src/my.py file with:

from typer import Typer

from .utils.api import api_url
from .utils.console import print

URI = "my-endpoint"

app = Typer()


@app.callback()
def my():
    """
    Example sub-command module
    """


@app.command()
def endpoint():
    """
    Display an arbitrary API url
    """
    uri = api_url(URI)

    print(str(uri), title="My-endpoint example")

Then in src/alcli.py, registrer this new sub-commands module:

from .my import app as my_app

#...

app.add_typer(my_app, name="my")

Finally, test it by calling it in your terminal:

$ poetry run alwaysdata my endpoint
╭─ My-endpoint example ──────────────────────────────────────────────────────╮
│ https://api.alwaysdata.com//v1/my-endpoint/                                │
╰────────────────────────────────────────────────────────────────────────────╯

The build process is handled by Nuitka, with a few options tweaked in the build command living in the build task.

To produce a local build, run poetry alcli build. It will produce a ./tmp/alwaysdata single file containing an auto-extractable archive ready to be run on the very same architecture as the current host. You can test it with ./tmp/alwaysdata --help to check it.

Since the project lives in Github, it takes advantage of Github Workflows to build artifacts for all supported platforms (Windows, MacOS, Linux). Check the .github/workflows/build.yml for an overview of the distributed build process.

Artifacts compiled per platforms through Github Workkflows are available in the Actions: Build section of the project. Select the related commit. Artifacts are located at the bottom of the page.