Command-line Interface

BYCEPS comes with a command-line tool for some tasks.


Before attempting to run any byceps command, make sure that the virtual environment is set up and activated.



byceps create-database-tables

Create database tables

byceps create-superuser

Create superuser

byceps export-roles

Export authorization roles

byceps generate-secret-key

Generate secret key

byceps import-roles

Import authorization roles

byceps import-seats

Import seats

byceps import-users

Import users

byceps initialize-database

Initialize database

byceps shell

Run interactive shell

Create Database Tables

byceps create-database-tables creates the tables that are required to run BYCEPS in a relational database instance.

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps create-database-tables
Creating database tables ... done.


The database initialization command covers this command.

Import Authorization Roles

byceps import-roles imports authorization roles from a file in TOML format into BYCEPS.

By default, an initial set of roles provided with BYCEPS is imported:

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps import-roles
Importing roles ... done. Imported 35 roles, skipped 0 roles.

Optionally, the file to import from can be specified with the option -f/--file:

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps import-roles -f custom_roles.toml
Importing roles ... done. Imported 35 roles, skipped 0 roles.


The database initialization command covers this command (except for the option to provide a custom roles file).

Export Authorization Roles

byceps export-roles exports authorization roles in TOML format from BYCEPS to standard output.

To export all roles into a TOML file, standard output is redirected (>) to it:

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps export-roles > exported-roles.toml

Initialize Database

byceps initialize-database prepares a relational database instance for running BYCEPS.

It is a convenience command that includes the following steps (making it unnecessary to call the covered commands separately):

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps initialize-database
Creating database tables ... done.
Importing roles ... done. Imported 35 roles, skipped 0 roles.
Adding language "en" ... done.
Adding language "de" ... done.

Create Superuser

byceps create-superuser creates a BYCEPS superuser.

This will:

  • create a user account,

  • initialize the account,

  • assign all existing authorization roles to the account, and

  • confirm the associated email address as valid (even though it might not be).

This command is necessary to create the initial user account, which then can be used to log in to the admin backend and to access all administrative functionality.

The command can be run to create additional user accounts as well, but they all will have superuser-like privileges in BYCEPS.

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps create-superuser
Screen name: Flynn
Email address:
Creating user "Flynn" ... done.
Enabling user "Flynn" ... done.
Assigning 35 roles to user "Flynn" ... done.


This command will only assign the roles that exist in the database. If no roles have been imported, none will be assigned.

Import Users

byceps import-users imports basic user accounts from a file in JSON Lines format into BYCEPS.

This functionality exists to support migration from another system to BYCEPS.

Currently supported fields:

  • screen_name (required)

  • email_address

  • legacy_id

  • first_name, last_name

  • date_of_birth

  • country, zip_code, city, street

  • phone_number

  • internal_comment

Example file (including a deliberately bad record):

{"screen_name": "imported01", "email_address": "imported01@example.test", "first_name": "Alice", "last_name": "Allison"}
{"bad": "data"}
{"screen_name": "imported02", "email_address": "imported02@example.test", "first_name": "Bob", "last_name": "Bobson"}
{"screen_name": "imported03"}

To import it:

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps import-users example-users.jsonl
[line 1] Imported user imported01.
[line 2] Could not import user: 1 validation error for UserToImport
  field required (type=value_error.missing)
[line 3] Imported user imported02.
[line 4] Imported user imported03.

Generate Secret Key

byceps generate-secret-key generates a secret key in a cryptographically secure way.

A secret key is, among other things, required for login sessions.

(venv)$ byceps generate-secret-key


Do not use the above key (or any other key you copied from anywhere). Generate your own secret key!


Do not use the same key for development and production environments. Generate separate secret keys!

Import Seats

byceps import-seats imports seats from a file in JSON Lines format into BYCEPS.

Currently supported fields:

  • area_title (required)

  • coord_x (required)

  • coord_y (required)

  • rotation

  • category_title (required)

  • label

  • type_

Example file:

{"area_title": "Floor 3", "coord_x": 10, "coord_y": 10, "rotation": 0, "category_title": "Premium", "label": "Seat A-1"}
{"area_title": "Floor 3", "coord_x": 25, "coord_y": 10, "rotation": 0, "category_title": "Premium", "label": "Seat A-2"}

To import it:

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps import-seats my-party-2023 example-seats.jsonl
[line 1] Imported seat (area="Floor 3", x=10, y=10, category="Premium").
[line 2] Imported seat (area="Floor 3", x=25, y=10, category="Premium").

Run Interactive Shell

The BYCEPS shell is an interactive Python command line prompt that provides access to BYCEPS’ functionality as well as the persisted data.

This can be helpful to inspect and manipulate the application’s data by using primarily the various services (from without directly accessing the database (hopefully limiting the amount of accidental damage).

(venv)$ BYCEPS_CONFIG=../config/development.toml byceps shell
Welcome to the interactive BYCEPS shell on Python 3.11.2!