Command Line Interface (bootstack)

The bootstack command-line interface is an optional productivity tool that helps you scaffold, develop, diagnose, and distribute bootstack applications. You can use bootstack with or without it — the CLI exists to reduce boilerplate, encourage a consistent project layout, and provide a smooth path from prototype to distributable application.

When to use the CLI

The CLI is most useful when:

• starting a new application
• maintaining a consistent project layout
• adding views, pages, or dialogs incrementally
• preparing an app for distribution
• diagnosing project or environment issues

For one-off scripts or experiments, manual setup may be simpler.

Top-level options

bootstack [--version] [--verbose] <command> [args]

Commands

bootstack start

Scaffold a new project.

bootstack start <name> [--template basic|appshell] [--theme <name>]
                   [--container grid|pack] [--simple] [--dir <path>]

The two templates produce different layouts:

# basic                              # appshell
my_app/                               my_app/
├── src/my_app/                       ├── src/my_app/
│   ├── __init__.py                   │   ├── __init__.py
│   ├── main.py                       │   ├── main.py
│   └── views/                        │   └── pages/
│       ├── __init__.py               │       ├── __init__.py
│       └── main_view.py              │       ├── home_page.py
├── assets/                           │       └── settings_page.py
├── bootstack.toml                         ├── assets/
└── README.md                         ├── bootstack.toml
                                      └── README.md

The chosen template is recorded in bootstack.toml as [app].template so other commands (like bootstack add page and bootstack add view) know which scaffolds are appropriate.

bootstack run

Run the application defined in bootstack.toml, or a specific Python file.

bootstack run [path]

• With no argument, walks up from the current directory until it finds a bootstack.toml, then runs [app].entry.
• With a directory, looks for bootstack.toml there.
• With a .py file, runs that file directly.

bootstack run adds <project>/src to PYTHONPATH and exports BOOTSTACK_THEME from [settings].theme so generated main.py files can pick the configured theme without hard-coding it.

bootstack add

Scaffold components inside an existing project.

bootstack add page <ClassName>      [--scrollable] [--dir <path>]   # appshell only
bootstack add view <ClassName>      [--container grid|pack] [--dir <path>]   # basic only
bootstack add dialog <ClassName>    [--dir <path>]
bootstack add theme <name>          [--mode light|dark]
bootstack add i18n                  [--languages <lang> ...]

add page and add view are gated by [app].template — running the wrong one in the wrong project type prints a clear error directing you to the other.

bootstack add page

Scaffolds a class-based page module under src/<module>/pages/. The command only creates the file — it does not modify main.py. After scaffolding it prints the import + add_page() call you need to paste into main.py, with placeholders for the page id, sidebar label, and icon name:

from <module>.pages.dashboard_page import DashboardPage
page = shell.add_page("<id>", text="<Label>", icon="<icon>")
DashboardPage(page)

Fill the placeholders in with values that fit your app — e.g. shell.add_page("dashboard", text="Dashboard", icon="speedometer2"). Icon names come from the Bootstrap Icons catalog.

--scrollable adjusts the printed hint so the suggested add_page() call includes scrollable=True.

bootstack add theme

Writes themes/<name>.json using the v2 theme schema (mode, shades, semantic, top-level foreground/background). To use the theme:

import bootstack as bs

bs.register_user_theme("mytheme", "themes/mytheme.json")
app = bs.App(theme="mytheme")

bootstack add i18n

Creates locales/<lang>/LC_MESSAGES/messages.po files for each language listed in --languages (defaults to en). Compile them with msgfmt before shipping.

bootstack list

Discover resources known to the framework.

bootstack list themes

Prints a table of every theme bundled with bootstack, including its display name and mode (light/dark). Useful for picking a value to pass to bootstack start --theme or to set in [settings].theme.

bootstack promote --pyinstaller

Add packaging support to an existing project.

bootstack promote --pyinstaller [--force]

This step:

1. Adds a [build] section to bootstack.toml (backend, windowed/console mode, onefile vs. onedir, icon path, asset-include patterns).
2. Generates build/pyinstaller/app.spec — a PyInstaller spec file that reads bootstack.toml at build time.

If PyInstaller isn't installed in the current interpreter, promote prints a note pointing at pip install pyinstaller. The promote step itself only writes config — it doesn't need PyInstaller to run.

--force overwrites existing build configuration.

bootstack build

Build the application.

bootstack build [--clean]

Runs PyInstaller against the spec generated by promote. --clean wipes dist/ and the PyInstaller work directory first.

The default Windows launch icon (visible in Explorer and on the taskbar) is the bundled bootstack icon. To override it, set [build.icon].path in bootstack.toml to a .ico (Windows) or .icns (macOS) file.

bootstack doctor

Diagnose project and environment health.

bootstack doctor

Reports:

• Python and Tcl/Tk versions
• bootstack version
• Whether bootstack.toml exists and parses
• Whether the entry point file exists
• Whether the directory layout matches [app].template (pages/ for appshell, views/ for basic)
• PyInstaller availability (always — even before promote, so users know whether they have a pip install ahead of them)

Returns exit code 1 if any checks fail; warnings (e.g. PyInstaller not installed) never fail the command.

bootstack gallery

Launch the AppShell-based widget gallery.

bootstack gallery

Useful for browsing every widget category, trying themes, and seeing example spec values for buttons, forms, tables, and dialogs.

bootstack icons

Launch the standalone Bootstrap Icons browser.

bootstack icons

Delegates to the ttkbootstrap-icons tool from the ttkbootstrap_icons_bs package, which ships a full searchable Bootstrap Icons browser. Any icon name from the Bootstrap Icons catalog can be used as the icon= parameter on any bootstack widget.

Configuration: bootstack.toml

When present, the CLI reads configuration from bootstack.toml at the project root. The default layout produced by bootstack start:

[app]
name = "MyApp"
id = "com.example.myapp"
entry = "src/myapp/main.py"
template = "basic"           # or "appshell"

[settings]
theme = "bootstrap-light"
language = "en"
appearance = "system"        # system | light | dark

[layout]
default_container = "grid"   # grid | pack

# Added by `bootstack promote --pyinstaller`:
[build]
backend = "pyinstaller"
windowed = true
onefile = false

[build.icon]
# path = "assets/icon.ico"

[build.datas]
include = ["assets/**", "locales/**", "themes/**", "bootstack.toml"]

If no bootstack.toml exists, the CLI uses defaults and your application code remains authoritative at runtime via AppSettings.

What the CLI is not

• Not required to use bootstack.
• Not a runtime dependency — your built application doesn't import the CLI.
• Not a replacement for learning the framework. Everything the CLI generates is plain Python you can read, modify, or replace.

If you prefer a fully manual setup, you can ignore the CLI entirely.

Next steps

• Quick Start — build your first app
• Project Structure — file organization and packaging
• Build & Ship — distribution workflow
• App Settings — runtime configuration