Command Line Interface

The fullfinity-server CLI is the primary tool for managing your Fullfinity installation. It handles server startup, module management, and code generation.

Basic Usage

fullfinity-server -c config.yaml [options] [command]

The -c/--config flag is required for all operations.

Starting the Server

Basic Server Start

fullfinity-server -c config.yaml

This starts the server using settings from config.yaml. The API will be available at http://localhost:8000 by default.

Start with Specific Database

fullfinity-server -c config.yaml -db mycompany

In multi-tenant setups, use -db to specify which database to connect to.

Custom Host and Port

fullfinity-server -c config.yaml --host 127.0.0.1 --port 9000

Override the default binding address and port.

Custom Worker Count

fullfinity-server -c config.yaml --workers 8

Override the number of worker processes (default from config file).

Rebuild Frontend Before Starting

fullfinity-server -c config.yaml --rebuild

Rebuilds the React frontend from source (app/) and copies the built files to static/ before starting the server.

Module Management

All module operations require the -db flag to specify the target database.

Discover New Modules

fullfinity-server -c config.yaml -db mycompany --update-module-list

Scans the addon paths for new or updated modules and registers them in the database. Run this after adding new module folders.

Install Modules

# Install single module
fullfinity-server -c config.yaml -db mycompany -i sales

# Install multiple modules
fullfinity-server -c config.yaml -db mycompany -i sales,invoicing,crm

# Long form
fullfinity-server -c config.yaml -db mycompany --install sales,invoicing

Installs the specified modules and their dependencies. The installation process:

1. Resolves module dependencies
2. Runs database migrations
3. Loads security groups and access rules
4. Loads views, actions, and menus
5. Loads seed data

Update Modules

# Update specific modules
fullfinity-server -c config.yaml -db mycompany -u sales,invoicing

# Update all installed modules
fullfinity-server -c config.yaml -db mycompany -u all

# Long form
fullfinity-server -c config.yaml -db mycompany --update all

Updates modules to apply changes:

• New or modified fields (runs schema migration)
• Updated views and actions
• New security rules
• Updated seed data

Uninstall Modules

fullfinity-server -c config.yaml -db mycompany --uninstall sales

Removes a module and cleans up:

• Deletes records owned by the module
• Updates dependent modules to restore their original state
• Reverts any extensions made by the uninstalled module

Warning: Uninstalling a module may delete user data associated with that module.

Initialize Modules (New Database)

fullfinity-server -c config.yaml -db newcompany --init core,sales,invoicing

Combines --update-module-list and --install for new database setup. Use this when setting up a fresh tenant database.

Module Operations Without Starting Server

fullfinity-server -c config.yaml -db mycompany -u all --stop-after-init

The --stop-after-init flag performs the module operations and exits without starting the server. Useful for:

• CI/CD pipelines
• Database updates in deployment scripts
• Batch operations

Upgrades

upgrade is an alias for -u all — there is no separate version-based upgrade path. After pulling new code, run either:

git pull origin main
fullfinity-server -c config.yaml -db mycompany -u all      # or: ... upgrade

This runs the additive schema sync and replays the schema-change ledger (renames, deletes, complex/data migrations) in one atomic transaction — per installed module, in change-id order. It’s safe to re-run (idempotent) and rolls back wholesale on failure. There are no pre_upgrade/post_upgrade hooks and no framework-version gating.

See Migrations & Upgrades for how schema changes are recorded (--check-schema / --resolve-schema) and replayed.

Custom Addon Paths

fullfinity-server -c config.yaml --addons-path ./fullfinity/modules,./addons,/opt/addons

Override the module search paths. Fullfinity will scan all specified directories for modules.

Scaffolding a New Module

The new command scaffolds a module with the standard directory structure and sample files.

fullfinity-server -c config.yaml new my_module

# Create it in a specific directory (default: current directory)
fullfinity-server -c config.yaml new my_module --path ./addons

The module identifier must be a snake_case identifier (letters, digits, underscores; not starting with a digit). The scaffolder writes a ready-to-install module:

my_module/
├── __init__.py
├── manifest.yaml         # Module metadata
├── models/               # Model definitions (.py) — includes models/__init__.py
├── views/                # UI views, actions, menus (.yaml)
├── security/             # Groups, permissions (.yaml)
├── data/                 # Seed data
├── demo/                 # Demo data
├── i18n/                 # Translations
├── tests/                # Tests (.py)
├── templates/            # Templates
├── routes/               # Custom routes
└── static/src/{css,js}/  # Frontend assets

The generated models/, views/, security/, and tests/ folders contain working sample files (a model, list/form views, an action, a menu, a security group, and a test). After scaffolding, install it:

fullfinity-server -c config.yaml -db mycompany -i my_module

Note: new does not require the -db flag since no database access is needed.

Command Reference

Global Options

Option	Short	Description
--config	-c	Path to configuration file (required)
--database	-db	Target database name
--help	-h	Show help message

Server Options

Option	Description
--host	Host to bind to (default: 0.0.0.0)
--port	Port to run on (default: 8000)
--workers	Number of worker processes
--rebuild	Rebuild frontend before starting
--addons-path	Comma-separated addon directories

Module Options

Option	Short	Description
--install	-i	Install modules (comma-separated)
--update	-u	Update modules (comma-separated or “all”)
--uninstall		Uninstall modules (comma-separated)
--init		Initialize modules (update list + install)
--update-module-list		Scan for new modules
--stop-after-init		Exit after module operations

Upgrade Subcommand

fullfinity-server -c config.yaml -db mycompany upgrade

Alias for -u all: additive schema sync + atomic ledger replay. Requires -db.

New Subcommand

# Scaffold a new module (no -db required)
fullfinity-server -c config.yaml new my_module [--path DIR]

new options:

Option	Description
name	Module identifier (snake_case), e.g. my_module (positional)
--path	Directory to create the module in (default: current directory)

Test Subcommand

fullfinity-server -c config.yaml -db mydb test [options]

test options:

Option	Short	Description
--module	-m	Only run tests for this module
--verbose	-v	Verbose output
-k		Only run tests matching this pattern
--json-summary		Write JSON test results to a file

Common Workflows

Setting Up a New Tenant

# Create database (via psql or your preferred method)
createdb newclient

# Initialize with core modules
fullfinity-server -c config.yaml -db newclient --init core,sales,crm --stop-after-init

# Start server for the tenant
fullfinity-server -c config.yaml -db newclient

Deploying a Version Update

# Pull new version
git pull origin main

# Upgrade after pulling new code (alias for -u all)
fullfinity-server -c config.yaml -db production upgrade

# Start server
fullfinity-server -c config.yaml -db production

The upgrade command handles both schema updates and data upgrade hooks. No separate -u all step is needed.

Deploying Module Updates (Same Version)

# Pull latest code (same framework version, module changes only)
git pull origin main

# Update all modules on production database
fullfinity-server -c config.yaml -db production -u all --stop-after-init

# Restart server (handled by process manager)

Adding a Custom Module

# Scaffold module structure
fullfinity-server -c config.yaml new custom_module

# Or create manually:
# mkdir -p modules/custom_module/{models,views,data,security,templates}
# Create manifest.json, models, views...

# Register the module
fullfinity-server -c config.yaml -db mycompany --update-module-list

# Install it
fullfinity-server -c config.yaml -db mycompany -i custom_module

Development Workflow

# Make changes to module code

# Update the module to apply changes
fullfinity-server -c config.yaml -db dev -u mymodule --stop-after-init

# Or update and start server in one command
fullfinity-server -c config.yaml -db dev -u mymodule

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error

Environment Variables

The CLI reads one environment variable, FULLFINITY_CONFIG_PATH, which records the path to the config file so worker processes (Gunicorn/Uvicorn workers, the job runner) can load it. It is set automatically from the -c/--config flag — you normally don’t set it by hand:

export FULLFINITY_CONFIG_PATH=./config.yaml

Individual configuration keys (DB_HOST, SECRET_KEY, etc.) are not overridable via environment variables — they are read from config.yaml (and a sibling config.local.yaml overlay). See Configuration.

Next Steps

• Configuration - Configure your installation
• Quick Start - Create your first module
• Creating Modules - Module development guide