Commands¶

The command modules implement the CLI commands for repository management, installation, testing, and more.

dbx_python_cli.commands.branch module¶

Branch command for running git branch in repositories.

dbx_python_cli.commands.branch.branch_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, git_args: list[str] = <typer.models.ArgumentInfo object>, group: str = <typer.models.OptionInfo object>, all_groups: bool = <typer.models.OptionInfo object>)[source]¶

Run git branch in a cloned repository or group of repositories.

Usage:

dbx branch <repo_name> [git_args...]
dbx branch -g <group_name> [git_args...]
dbx branch -a [git_args...]

Examples:

dbx branch mongo-python-driver                 # Show local branches
dbx -v branch mongo-python-driver              # Show all branches (local and remote)
dbx branch mongo-python-driver -d feature      # Delete branch 'feature'
dbx branch mongo-python-driver -D feature      # Force delete branch 'feature'
dbx branch -g pymongo                          # Show branches for all repos in group
dbx -v branch -g pymongo                       # Show all branches for all repos in group
dbx branch -g pymongo -d old-feature           # Delete 'old-feature' in all repos
dbx branch -a                                  # Show branches for all repos in all groups
dbx -v branch -a                               # Show all branches for all repos in all groups

dbx_python_cli.commands.clone module¶

Clone command for cloning repositories.

dbx_python_cli.commands.clone.auto_install_repo(repo_path: Path, repo_name: str, group_name: str, base_dir: Path, verbose: bool = False)[source]¶

Automatically install a cloned repository.

Parameters:

repo_path – Path to the cloned repository
repo_name – Name of the repository
group_name – Name of the group the repo belongs to
base_dir – Path to the base directory
verbose – Whether to show verbose output

dbx_python_cli.commands.clone.clone_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, group: list[str] = <typer.models.OptionInfo object>, all_groups: bool = <typer.models.OptionInfo object>, fork: bool = <typer.models.OptionInfo object>, fork_user: str = <typer.models.OptionInfo object>, no_install: bool = <typer.models.OptionInfo object>)[source]¶: Clone a repository by name, all repositories from one or more groups, or all groups.

dbx_python_cli.commands.clone.ensure_group_venv(group_dir: Path, group_name: str, verbose: bool = False, python_version: str = None) → bool[source]¶

Ensure a group-level virtual environment exists, creating one if needed.

Parameters:

group_dir – Path to the group directory
group_name – Name of the group
verbose – Whether to show verbose output
python_version – Python version to use (e.g., ‘3.13’), or None for system default

Returns:

True if venv exists or was created successfully, False otherwise

dbx_python_cli.commands.clone.ensure_repo_venv(repo_path: Path, repo_name: str, verbose: bool = False, python_version: str = None) → bool[source]¶

Ensure a repo-level virtual environment exists, creating one if needed.

Parameters:

repo_path – Path to the repository directory
repo_name – Name of the repository
verbose – Whether to show verbose output
python_version – Python version to use (e.g., ‘3.13’), or None for system default

Returns:

True if venv exists or was created successfully, False otherwise

dbx_python_cli.commands.config module¶

Configuration management commands.

dbx_python_cli.commands.config.edit()[source]¶

Edit the configuration file with your default editor.

Opens the configuration file using the editor specified in the EDITOR environment variable. If EDITOR is not set, falls back to common editors (vim, nano, vi) or uses ‘open’ on macOS.

Examples:

dbx config edit                    # Open with default editor
EDITOR=code dbx config edit        # Open with VS Code
EDITOR=nano dbx config edit        # Open with nano

dbx_python_cli.commands.config.init(yes: bool = <typer.models.OptionInfo object>, remove_base_dir: bool = <typer.models.OptionInfo object>)[source]¶: Initialize user configuration file.

dbx_python_cli.commands.config.show(ctx: Context)[source]¶

Display the current configuration.

Shows the active configuration being used by dbx, including the config file location and all settings.

Examples:

dbx config show                    # Display current configuration

dbx_python_cli.commands.edit module¶

Edit command for opening repositories in an editor.

dbx_python_cli.commands.edit.edit_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>)[source]¶

Open a repository in your editor.

The editor is determined by the following priority: 1. Repo-specific editor setting in config.toml 2. Group-level editor setting in config.toml 3. Global editor setting in config.toml 4. EDITOR environment variable 5. Default to ‘vim’

Usage:

dbx edit <repo_name>

Examples:

dbx edit mongo-python-driver    # Open repo in configured editor

dbx_python_cli.commands.env module¶

Virtual environment management commands.

dbx_python_cli.commands.env.init(ctx: Context, repo: str = <typer.models.ArgumentInfo object>, group: str = <typer.models.OptionInfo object>, python: str = <typer.models.OptionInfo object>, list_groups: bool = <typer.models.OptionInfo object>)[source]¶

Create a virtual environment.

By default, creates a venv in the base directory (shared across all repos). Use –group to create a venv in a specific group directory. Use a positional repo argument to create a venv in an individual repo directory. Use both –group and repo to create a venv for a repo within a specific group.

dbx_python_cli.commands.env.list(ctx: Context)[source]¶: List all virtual environments (base, group, and repo level).

dbx_python_cli.commands.env.remove(ctx: Context, repo: str = <typer.models.ArgumentInfo object>, group: str = <typer.models.OptionInfo object>, list_groups: bool = <typer.models.OptionInfo object>, force: bool = <typer.models.OptionInfo object>)[source]¶

Remove a virtual environment.

By default, removes the venv from the base directory. Use –group to remove a venv from a specific group directory. Use a positional repo argument to remove a venv from an individual repo directory. Use both –group and repo to remove a venv for a repo within a specific group.

dbx_python_cli.commands.install module¶

Install command for installing dependencies in repositories.

dbx_python_cli.commands.install.get_package_options(work_dir)[source]¶

Extract available extras and dependency groups from pyproject.toml.

Parameters:: work_dir – Path to the directory containing pyproject.toml
Returns:: Dictionary with ‘extras’ and ‘dependency_groups’ lists
Return type:: dict

dbx_python_cli.commands.install.install_as_sys_path(repo_path: Path, python_path: str, verbose: bool = False) → str[source]¶

Add repo_path to the venv’s sys.path via a .pth file in site-packages.

Used for repos without a pyproject.toml/setup.py that just need to be importable. Returns “success” or “failed”.

dbx_python_cli.commands.install.install_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, extras: list[str] | None = <typer.models.OptionInfo object>, dependency_groups: str | None = <typer.models.OptionInfo object>, group: list[str] | None = <typer.models.OptionInfo object>, show_options: bool = <typer.models.OptionInfo object>, repo_group: str | None = <typer.models.OptionInfo object>, list_repos: bool = <typer.models.OptionInfo object>)[source]¶: Install dependencies in a cloned repository using uv pip install.

dbx_python_cli.commands.install.install_frontend_if_exists(repo_path, verbose=False)[source]¶

Check if a frontend directory exists and install npm dependencies if found.

Parameters:

repo_path – Path to the repository/project root
verbose – Whether to show verbose output

Returns:

True if frontend was found and installed successfully, False if no frontend or failed

Return type:

bool

dbx_python_cli.commands.install.install_package(repo_path, python_path, install_dir=None, extras=None, groups=None, verbose=False)[source]¶

Install a package from a directory.

Parameters:

repo_path – Path to the repository root
python_path – Path to Python executable
install_dir – Subdirectory to install from (for repos with multiple packages), or None for root
extras – Comma-separated extras to install
groups – Comma-separated dependency groups to install
verbose – Whether to show verbose output

Returns:

“success” if successful, “skipped” if no setup.py/pyproject.toml, “failed” otherwise

Return type:

str

dbx_python_cli.commands.install.run_build_commands(repo_path, build_commands, verbose=False)[source]¶

Run build commands for a repository.

Parameters:

repo_path – Path to the repository root
build_commands – List of shell commands to run
verbose – Whether to show verbose output

Returns:

True if all commands succeeded, False otherwise

Return type:

bool

dbx_python_cli.commands.just module¶

Just command for running just commands in repositories.

dbx_python_cli.commands.just.has_justfile(repo_path: Path) → bool[source]¶: Check if a repository has a justfile.

dbx_python_cli.commands.just.just_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, just_args: list[str] = <typer.models.ArgumentInfo object>, group: str = <typer.models.OptionInfo object>)[source]¶

Run just commands in a cloned repository.

Usage:

dbx just <repo_name> [just_command] [args...]
dbx just -g <group> <repo_name> [just_command] [args...]
dbx just list                         # List repos with justfiles

If a just command is provided after the repo name, it will be executed. If no just command is provided, ‘just’ will be run without arguments to show available commands.

Examples:

dbx just mongo-python-driver          # Show available just commands
dbx just mongo-python-driver lint     # Run 'just lint'
dbx just mongo-python-driver test -v  # Run 'just test -v'
dbx just -g pymongo mongo-python-driver lint  # Run in pymongo group
dbx just list                         # List repos with justfiles

dbx_python_cli.commands.just.list_command(ctx: Context)[source]¶

List all repositories that have justfiles.

Shows all cloned repositories that have a justfile or Justfile, organized by group.

Examples:

dbx just list    # List repos with justfiles

dbx_python_cli.commands.list module¶

List command for listing repositories.

dbx_python_cli.commands.list.list_callback(ctx: Context)[source]¶

List all repositories (cloned and available).

Shows a tree view of all repository groups with status indicators: - ✓ = cloned - ○ = available to clone - ? = cloned but not in config

Examples:

dbx list                    # List all repositories

dbx_python_cli.commands.log module¶

Log command for showing git commit logs.

dbx_python_cli.commands.log.log_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, git_args: list[str] = <typer.models.ArgumentInfo object>, group: str = <typer.models.OptionInfo object>, all_groups: bool = <typer.models.OptionInfo object>, project: str = <typer.models.OptionInfo object>)[source]¶

Show git commit logs from a repository or group of repositories.

Usage:

dbx log <repo_name> [git_args...]
dbx log -g <group> [git_args...]
dbx log -a [git_args...]
dbx log --project <project> [git_args...]

Examples:

dbx log mongo-python-driver                    # Show entire log (paginated)
dbx log mongo-python-driver -n 5               # Show last 5 commits
dbx log mongo-python-driver --oneline          # Show entire log in oneline format
dbx log mongo-python-driver --graph -n 5       # Show graph with last 5 commits
dbx log -g pymongo -n 20                       # Show last 20 commits for all repos
dbx log -g pymongo --oneline -n 5              # Show last 5 commits in oneline format
dbx log -a --oneline -n 5                      # Show last 5 commits for all cloned repos
dbx log --project myproject -n 5               # Show last 5 commits for a project

dbx_python_cli.commands.open module¶

Open command for opening repositories in a web browser.

dbx_python_cli.commands.open.open_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, group: str = <typer.models.OptionInfo object>)[source]¶

Open a repository or group of repositories in a web browser.

Usage:

dbx open <repo_name>
dbx open -g <group_name>

Examples:

dbx open mongo-python-driver    # Open repo in browser
dbx open -g pymongo              # Open all repos in group

dbx_python_cli.commands.project module¶

Project management commands.

dbx_python_cli.commands.project.add_project(name: str = <typer.models.ArgumentInfo object>, directory: Path = <typer.models.OptionInfo object>, base_dir: Path = <typer.models.OptionInfo object>, add_frontend: bool = <typer.models.OptionInfo object>, add_wagtail: bool = <typer.models.OptionInfo object>, add_qe: bool = <typer.models.OptionInfo object>, add_bakerydemo: bool = <typer.models.OptionInfo object>, auto_install: bool = <typer.models.OptionInfo object>, python_path_override: str | None = <typer.models.OptionInfo object>, with_repos: List[str] = <typer.models.OptionInfo object>)[source]¶

Create a new Django project using bundled templates. Frontend is added by default. Use –no-frontend to skip frontend creation. Use –wagtail to create a Wagtail project from wagtail-mongodb-project. Use –bakerydemo (with –wagtail) to clone and install bakerydemo into the venv. Use –qe to enable Queryable Encryption.

Projects are created in base_dir/projects/ by default. If no name is provided, a random name is generated.

Examples:

dbx project add                          # Create with random name (includes frontend)
dbx project add myproject                # Create with explicit name (includes frontend)
dbx project add myproject --no-frontend  # Create without frontend
dbx project add myproject --wagtail      # Create Wagtail project from wagtail-mongodb-project
dbx project add myproject --qe           # Create with Queryable Encryption enabled
dbx project add -d ~/custom/path         # Create with random name in custom directory
dbx project add myproject -d ~/custom/path        # Create in custom directory
dbx project add myproject --base-dir ~/path/to/myproject  # Create directly at path
dbx project add myproject --with medical-records           # Install a local clone
dbx project add myproject --with django --with django-mongodb-extensions

dbx_python_cli.commands.project.create_superuser(ctx: Context, name: str = <typer.models.ArgumentInfo object>, directory: Path = <typer.models.OptionInfo object>, username: str = <typer.models.OptionInfo object>, password: str = <typer.models.OptionInfo object>, email: str = <typer.models.OptionInfo object>, mongodb_uri: str = <typer.models.OptionInfo object>, settings: str = <typer.models.OptionInfo object>)[source]¶

Create a Django superuser with no interaction required.

If no project name is provided, uses the most recently created project.

Examples:

dbx project su                          # Create superuser on newest project
dbx project su myproject
dbx project su myproject --settings base
dbx project su myproject -u myuser -p mypass
dbx project su myproject -e admin@example.com

dbx_python_cli.commands.project.edit_project(name: str = <typer.models.ArgumentInfo object>, directory: Path = <typer.models.OptionInfo object>, settings: str = <typer.models.OptionInfo object>)[source]¶

Edit project settings files with your default editor.

Opens all files in the project’s settings/ directory by default. Pass –settings to open a single specific file instead.

Uses the editor from the EDITOR environment variable; falls back to vim, nano, vi, or ‘open’ on macOS.

If no project name is provided, uses the most recently created project.

Examples:

dbx project edit                      # Edit all settings files
dbx project edit myproject            # Edit myproject's settings files
dbx project edit myproject --settings base  # Edit only base settings
dbx project edit myproject -s qe      # Edit only qe settings
EDITOR=code dbx project edit          # Open with VS Code

dbx_python_cli.commands.project.generate_random_project_name()[source]¶: Generate a random project name using adjectives and nouns.

dbx_python_cli.commands.project.install_project(name: str = <typer.models.ArgumentInfo object>, directory: Path = <typer.models.OptionInfo object>, extras: str = <typer.models.OptionInfo object>, verbose: bool = <typer.models.OptionInfo object>)[source]¶

Install a Django project’s dependencies.

If no project name is provided, uses the most recently created project.

Examples:

dbx project install                    # Install newest project
dbx project install myproject          # Install specific project
dbx project install myproject -e test  # Install with extras

dbx_python_cli.commands.project.list_projects()[source]¶: List all projects in the projects directory.

dbx_python_cli.commands.project.manage(ctx: Context, name: str = <typer.models.ArgumentInfo object>, command: str = <typer.models.ArgumentInfo object>, args: list[str] = <typer.models.ArgumentInfo object>, directory: Path = <typer.models.OptionInfo object>, mongodb_uri: str = <typer.models.OptionInfo object>, database: str = <typer.models.OptionInfo object>, settings: str = <typer.models.OptionInfo object>)[source]¶

Run any Django management command for a project.

If no project name is provided, uses the most recently created project.

Examples:

dbx project manage shell                # Run shell on newest project
dbx project manage myproject shell
dbx project manage myproject createsuperuser
dbx project manage myproject --mongodb-uri mongodb+srv://user:pwd@cluster
dbx project manage myproject --settings base shell
dbx project manage myproject migrate --database default

dbx_python_cli.commands.project.migrate_project(ctx: Context, name: str = <typer.models.ArgumentInfo object>, directory: Path = <typer.models.OptionInfo object>, database: str = <typer.models.OptionInfo object>, mongodb_uri: str = <typer.models.OptionInfo object>, settings: str = <typer.models.OptionInfo object>)[source]¶

Run Django migrations on a project.

If no project name is provided, uses the most recently created project.

Examples:

dbx project migrate                          # Migrate newest project
dbx project migrate myproject
dbx project migrate myproject --settings base
dbx project migrate myproject --database encrypted

dbx_python_cli.commands.project.open_browser(host: str = <typer.models.OptionInfo object>, port: int = <typer.models.OptionInfo object>)[source]¶

Open localhost in the browser.

Examples:

dbx project open                    # Opens http://localhost:8000
dbx project open --port 3000        # Opens http://localhost:3000
dbx project open --host 127.0.0.1   # Opens http://127.0.0.1:8000

dbx_python_cli.commands.project.project_callback(ctx: Context)[source]¶: Project management commands.

dbx_python_cli.commands.project.remove_project(name: str = <typer.models.ArgumentInfo object>, directory: Path = <typer.models.OptionInfo object>)[source]¶

Delete a Django project by name.

If no project name is provided, removes the most recently created project. This will first attempt to uninstall the project package using pip in the current Python environment, then remove the project directory.

Examples:

dbx project remove                # Remove newest project
dbx project remove myproject      # Remove specific project

dbx_python_cli.commands.project.run_project(ctx: Context, name: str = <typer.models.ArgumentInfo object>, directory: Path = <typer.models.OptionInfo object>, host: str = <typer.models.OptionInfo object>, port: int = <typer.models.OptionInfo object>, settings: str = <typer.models.OptionInfo object>)[source]¶

Run a Django project with manage.py runserver.

If no project name is provided, runs the most recently created project. If a frontend directory exists, it will be run automatically alongside the Django server.

Examples:

dbx project run                      # Run newest project
dbx project run myproject
dbx project run myproject --settings base
dbx project run myproject -s qe --port 8080

dbx_python_cli.commands.remove module¶

Remove command for removing repositories or repository groups.

dbx_python_cli.commands.remove.remove_callback(ctx: Context, repo_names: List[str] | None = <typer.models.ArgumentInfo object>, group: str | None = <typer.models.OptionInfo object>, repo_group: str | None = <typer.models.OptionInfo object>, force: bool = <typer.models.OptionInfo object>)[source]¶

Remove repositories or repository groups.

Examples:

dbx remove mongo-python-driver              # Remove a single repo
dbx remove repo1 repo2 repo3                # Remove multiple repos
dbx remove mongo-python-driver -G langchain # Remove from specific group
dbx remove -g pymongo                       # Remove all repos in group
dbx remove -g pymongo -f                    # Remove without confirmation

dbx_python_cli.commands.status module¶

Status command for showing git status of repositories.

dbx_python_cli.commands.status.status_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, group: str = <typer.models.OptionInfo object>, short: bool = <typer.models.OptionInfo object>)[source]¶

Show git status of repositories.

Usage:

dbx status <repo_name>           # Show status of a single repository
dbx status -g <group_name>       # Show status of all repos in a group
dbx status -g <group_name> <repo_name>  # Show status of specific repo in group

Examples:

dbx status django-mongodb-backend        # Show status of single repo
dbx status -g django                     # Show status of all repos in django group
dbx status -g django django              # Show status of django repo in django group
dbx status --short django-mongodb-backend # Show short-format status

dbx_python_cli.commands.switch module¶

Switch command for switching git branches in repositories.

dbx_python_cli.commands.switch.switch_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, branch_name: str = <typer.models.ArgumentInfo object>, list_repos: bool = <typer.models.OptionInfo object>, group: str = <typer.models.OptionInfo object>, project: str = <typer.models.OptionInfo object>, create: bool = <typer.models.OptionInfo object>)[source]¶

Switch to a branch in a cloned repository, group of repositories, or project.

Usage:

dbx switch <repo_name> <branch_name>
dbx switch -g <group_name> <branch_name>
dbx switch -p <project_name> <branch_name>

Examples:

dbx switch mongo-python-driver PYTHON-5683       # Switch to branch
dbx switch mongo-python-driver main              # Switch to main
dbx switch -c mongo-python-driver feature-123    # Create and switch to new branch
dbx switch -g pymongo PYTHON-5683                # Switch all repos in group
dbx switch -p myproject feature-branch           # Switch project branch

dbx_python_cli.commands.sync module¶

Sync command for syncing repositories with upstream.

dbx_python_cli.commands.sync.sync_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, group: str = <typer.models.OptionInfo object>, all_groups: bool = <typer.models.OptionInfo object>, force: bool = <typer.models.OptionInfo object>, dry_run: bool = <typer.models.OptionInfo object>)[source]¶

Sync repository with upstream by fetching, rebasing, and pushing.

Rebase behavior:

Main/master branches: Rebases to upstream/main or upstream/master
Feature branches: Rebases to upstream’s default branch (main/master)

This allows you to keep your main branch in sync with upstream/main, while also keeping feature branches up-to-date with the latest upstream changes.

Usage:

dbx sync <repo_name>                    # Sync a single repository
dbx sync -g <group>                     # Sync all repos in a group
dbx sync -a                             # Sync all repos in all groups
dbx sync -g <group> <repo_name>         # Sync specific repo in a group
dbx sync <repo_name> --force            # Force push after rebasing
dbx sync <repo_name> --dry-run          # Show what would be synced
dbx sync -g <group> --dry-run           # Preview group sync without changes
dbx sync -a --dry-run                   # Preview all groups sync without changes
dbx sync -g <group> <repo_name> --dry-run  # Preview single repo in group

Examples:

dbx sync mongo-python-driver                    # Sync single repo
dbx sync -g pymongo                             # Sync all repos in group
dbx sync -a                                     # Sync all repos in all groups
dbx sync -g pymongo mongo-python-driver         # Sync specific repo in pymongo group
dbx sync my-repo --force                        # Force push after rebase
dbx sync my-repo --dry-run                      # Preview changes without syncing
dbx sync -g pymongo --dry-run                   # Preview group sync
dbx sync -a --dry-run                           # Preview all groups sync
dbx sync -g pymongo mongo-python-driver --dry-run  # Preview specific repo

dbx_python_cli.commands.test module¶

Test command for running pytest in repositories.

dbx_python_cli.commands.test.test_callback(ctx: Context, repo_name: str = <typer.models.ArgumentInfo object>, test_args: list[str] = <typer.models.ArgumentInfo object>, keyword: str = <typer.models.OptionInfo object>, group: str | None = <typer.models.OptionInfo object>, list_repos: bool = <typer.models.OptionInfo object>, yes: bool = <typer.models.OptionInfo object>)[source]¶

Run tests in a cloned repository.

Usage:

dbx test <repo_name> [test_args...]
dbx test <repo_name> -k <keyword>
dbx test <repo_name> -g <group>

Examples:

dbx test mongo-python-driver                    # Run pytest
dbx test mongo-python-driver -v                 # Run pytest with verbose
dbx test mongo-python-driver -k test_insert     # Run specific test
dbx test django --verbose                       # Run custom test runner with args