### Installation Commands: install Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Example for complete installation.

```bash
invenio-cli install --pre --dev --development
```

--------------------------------

### DockerHelper start_containers Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of starting Docker containers.

```python
response = helper.start_containers(app_only=False)
if response.status_code == 0:
    print("Containers started")
```

--------------------------------

### Get Services Setup Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-config.md

Checks if services (databases, Elasticsearch, etc.) have been initialized.

```python
if config.get_services_setup():
    print("Services already initialized")
```

--------------------------------

### Start and setup services

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Start and set up necessary services like database, Elasticsearch, and Redis for local development.

```console
# Start and setup services (database, Elasticsearch, Redis, queue)
$ invenio-cli services
```

--------------------------------

### Services and Containers: containers Example 2

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Build and start containerized Invenio application with specific options.

```bash
invenio-cli containers --no-cache --pull
```

--------------------------------

### Services and Containers: containers Example 1

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Build and start containerized Invenio application.

```bash
invenio-cli containers
```

--------------------------------

### CommandStep example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of creating and executing a CommandStep to install a Python package.

```python
from invenio_cli.commands.steps import CommandStep

step = CommandStep(
    cmd=["pip", "install", "invenio"],
    env={"PIP_INDEX_URL": "https://pypi.org/simple/"},
    message="Installing Invenio...",
    skippable=True
)
response = step.execute()
```

--------------------------------

### LocalCommands.run_web() Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Example of starting the local development web server.

```python
commands = LocalCommands(config)
processes = commands.run_web(host="127.0.0.1", port="5000", debug=True)
for proc in processes:
    proc.wait()  # Block until process exits
```

--------------------------------

### DockerHelper Constructor Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of initializing DockerHelper.

```python
from invenio_cli.helpers.docker_helper import DockerHelper

helper = DockerHelper("my-invenio")
```

--------------------------------

### Installation Commands: install (default)

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Complete installation: Python dependencies, symlinks, and assets.

```bash
invenio-cli install [all] [OPTIONS]
```

--------------------------------

### run_interactive example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example usage of the run_interactive function to install npm packages with custom environment variables and logging.

```python
response = run_interactive(
    ["npm", "install"],
    env={"VERBOSE": "1"},
    log_file="/tmp/install.log"
)
```

--------------------------------

### Get Instance Path Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-config.md

Demonstrates how to safely retrieve the instance path, handling potential errors.

```python
try:
    instance_path = config.get_instance_path()
except InvenioCLIConfigError:
    print("Instance not yet initialized")

# Or safely check without exception
instance_path = config.get_instance_path(throw=False)
if instance_path:
    print(f"Instance at: {instance_path}")
```

--------------------------------

### .invenio Configuration Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Example of a project-wide .invenio configuration file.

```ini
[cli]
flavour = RDM
logfile = /logs/invenio-cli.log
python_package_manager = pipenv
javascript_package_manager = npm

[cookiecutter]
project_shortname = my-invenio
project_name = My Invenio Instance
database = postgresql
search = elasticsearch7
file_storage = local
author_name = John Doe
author_email = john@example.com

[files]
# ... generated files tracked during init
```

--------------------------------

### Minimal .invenio.private configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of a minimal .invenio.private configuration file for instance path and service setup.

```ini
[cli]
instance_path = /Users/jane/projects/my-invenio/.venv/var/instance
services_setup = False
web_host = 127.0.0.1
web_port = 5000
search_host = localhost
search_port = 9200
```

--------------------------------

### Installation Commands: install assets

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Build and install JavaScript assets only.

```bash
invenio-cli install assets [OPTIONS]
```

--------------------------------

### Project Initialization: init Example 2

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Initialize with custom template.

```bash
# Initialize with custom template
invenio-cli init rdm --template https://github.com/user/template.git --checkout v1.0
```

--------------------------------

### Commands.pyshell() Examples

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Examples of starting an interactive Python shell with and without debug mode.

```python
# Start Python shell without debug
commands.pyshell()

# Start with debug mode enabled
commands.pyshell(debug=True)
```

--------------------------------

### Install Invenio-Cli

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/INSTALL.rst

This command installs the Invenio-Cli package from PyPI.

```console
$ pip install invenio-cli
```

--------------------------------

### Services and Containers: services start

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Start existing Docker services.

```bash
invenio-cli services start
```

--------------------------------

### Commands.shell() Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Example of starting an interactive shell.

```python
commands = Commands(config)
exit_code = commands.shell()
```

--------------------------------

### Install locally

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Install Python dependencies, link/copy assets, install JS dependencies, and build assets for local development.

```console
# Install locally
# install python dependencies (pre-release versions needed for now),
# link/copy assets + statics, install js dependencies, build assets and
# final statics
$ invenio-cli install --pre
```

--------------------------------

### UV example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of using the UV package manager.

```python
from invenio_cli.helpers.package_managers import UV

uv = UV()
cmd = uv.run_command("invenio", "db", "init")
# Returns: ["uv", "run", "--no-sync", "invenio", "db", "init"]
```

--------------------------------

### Bash example for translations init

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Examples of initializing catalogs for German and French locales using the CLI.

```bash
invenio-cli translations init --locale de
invenio-cli translations init --locale fr
```

--------------------------------

### Start Development Servers

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/INDEX.md

Example of starting development servers (web and worker) for an Invenio project using the invenio-cli Python API.

```python
from invenio_cli.helpers.cli_config import CLIConfig
from invenio_cli.commands import LocalCommands

config = CLIConfig()
commands = LocalCommands(config)

# Start web and worker servers
processes = commands.run_all(
    host="127.0.0.1",
    port="5000",
    debug=True,
    services=True,
    celery_log_level="INFO"
)
```

--------------------------------

### Project Initialization: init Example 3

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Initialize with config file (no prompts).

```bash
# Initialize with config file (no prompts)
invenio-cli init rdm --no-input --config my-config.invenio
```

--------------------------------

### Installation Commands: install symlink

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Create symlinks for project files in instance directory.

```bash
invenio-cli install symlink
```

--------------------------------

### Services and Containers: services setup

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Initialize services: database, indices, admin role, file locations.

```bash
invenio-cli services setup
```

--------------------------------

### Python example for init command

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example demonstrating how to use the init function to create a .po file for a specific locale.

```python
steps = commands.init(
    output_dir="invenio_app_rdm/translations",
    input_file="messages.pot",
    locale="de"  # German
)
# Creates: invenio_app_rdm/translations/de/LC_MESSAGES/messages.po
```

--------------------------------

### Install Dependencies and Assets

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/INDEX.md

Example of installing dependencies and assets for an Invenio project using the invenio-cli Python API and CLI.

```python
from invenio_cli.helpers.cli_config import CLIConfig
from invenio_cli.commands import InstallCommands
from invenio_cli.cli.utils import run_steps

config = CLIConfig()
commands = InstallCommands(config)

# Get installation steps
steps = commands.install(pre=True, dev=True, debug=True)

# Execute with progress display
run_steps(steps, "Installation failed", "Installation successful")
```

```bash
invenio-cli install --pre --dev
```

--------------------------------

### Project Initialization: init Example 1

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Initialize RDM with prompts.

```bash
# Initialize RDM with prompts
invenio-cli init rdm
```

--------------------------------

### CLIConfig.write Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-config.md

Example usage of the CLIConfig.write method.

```python
from invenio_cli.helpers.cookiecutter_wrapper import CookiecutterWrapper
from invenio_cli.helpers.cli_config import CLIConfig

wrapper = CookiecutterWrapper("RDM")
project_dir = wrapper.cookiecutter()
replay = wrapper.get_replay()

CLIConfig.write(project_dir, "RDM", replay)
```

--------------------------------

### Installation Commands: install python

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Install Python dependencies only.

```bash
invenio-cli install python [OPTIONS]
```

--------------------------------

### .invenio.private Configuration Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Example of a machine-specific .invenio.private configuration file.

```ini
[cli]
instance_path = /workspace/venv/var/instance
services_setup = False
web_host = 127.0.0.1
web_port = 5000
search_host = localhost
search_port = 9200
```

--------------------------------

### Pipenv example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of using the Pipenv package manager.

```python
from invenio_cli.helpers.package_managers import Pipenv

pipenv = Pipenv()
cmd = pipenv.run_command("invenio", "db", "init")
# Returns: ["pipenv", "run", "invenio", "db", "init"]
```

--------------------------------

### Services and Containers: containers setup

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Initialize services inside containers.

```bash
invenio-cli containers setup
```

--------------------------------

### CookiecutterWrapper cookiecutter Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of running cookiecutter to generate a project.

```python
wrapper = CookiecutterWrapper("RDM")
project_dir = wrapper.cookiecutter()
print(f"Project created at: {project_dir}")
```

--------------------------------

### Production Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of a production configuration for Invenio CLI, including instance path, service setup, and network settings.

```ini
[cli]
instance_path = /opt/invenio/var/instance
services_setup = True

[cli]
web_host = 0.0.0.0
web_port = 8000
search_host = elasticsearch.internal
search_port = 9200
```

--------------------------------

### run web

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Starts web server only.

```bash
invenio-cli run web [OPTIONS]
```

```bash
invenio-cli run web --no-services
```

--------------------------------

### Services and Containers: containers

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Build and start containerized Invenio application.

```bash
invenio-cli containers [OPTIONS]
```

--------------------------------

### CookiecutterWrapper Constructor Examples

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Examples of initializing CookiecutterWrapper for RDM projects.

```python
from invenio_cli.helpers.cookiecutter_wrapper import CookiecutterWrapper

# RDM with defaults
wrapper = CookiecutterWrapper("RDM", no_input=True)

# Custom template
wrapper = CookiecutterWrapper(
    "RDM",
    template="https://github.com/user/custom-template.git",
    checkout="develop"
)

# With config file
wrapper = CookiecutterWrapper("RDM", config="/path/to/.invenio")
```

--------------------------------

### Get DB Type Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-config.md

Retrieves the configured database type.

```python
db = config.get_db_type()  # "postgresql" or "mysql"
```

--------------------------------

### Python example for compile command

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example demonstrating how to use the compile function to create binary .mo files.

```python
steps = commands.compile(
    fuzzy=False,  # Only use approved translations
    symlink=True  # Symlink to instance
)
# Creates: invenio_app_rdm/translations/de/LC_MESSAGES/messages.mo
```

--------------------------------

### Services and Containers: services

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Set up and start Docker services (database, Elasticsearch, Redis).

```bash
invenio-cli services
```

--------------------------------

### install

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Full installation: dependencies, symlinks, and assets.

```python
def install(self, pre: bool, dev: bool = False, debug: bool = False) -> list[Step]
```

```python
from invenio_cli.cli.utils import run_steps

commands = InstallCommands(config)
steps = commands.install(pre=True, dev=True, debug=True)
run_steps(steps, "Installation failed", "Installation successful")
```

--------------------------------

### CLI assets build Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example of how to use the CLI command to build all assets for production deployment. The output consists of minified, production-optimized static files.

```bash
invenio-cli assets build
```

--------------------------------

### run (default / all)

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Starts web server and worker simultaneously.

```bash
invenio-cli run [OPTIONS]
```

```bash
# Start with defaults
invenio-cli run

# Custom host/port without auto-reload
invenio-cli run --host 0.0.0.0 --port 8000 --no-debug
```

--------------------------------

### Package Management: packages install

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Install specified packages in editable (development) mode.

```bash
invenio-cli packages install <PACKAGES>... [OPTIONS]
```

--------------------------------

### ProcessResponse constructor example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of creating and using a ProcessResponse object.

```python
from invenio_cli.helpers.process import ProcessResponse

response = ProcessResponse(
    output="Installation complete",
    status_code=0
)

if response.status_code != 0:
    print(f"Error: {response.error}")
else:
    print(response.output)
```

--------------------------------

### Python example for update command

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example demonstrating how to use the update function to update .po files based on a .pot template.

```python
steps = commands.update(
    output_dir="invenio_app_rdm/translations",
    input_file="messages.pot"
)
# Updates all .po files (de, fr, es, etc.)
```

--------------------------------

### Python example for extract command

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example demonstrating how to use the extract function to generate a .pot template file.

```python
from invenio_cli.commands import TranslationsCommands
from invenio_cli.cli.utils import run_steps

commands = TranslationsCommands(config)
steps = commands.extract(
    babel_file="babel.ini",
    output_file="messages.pot",
    input_dirs="invenio_app_rdm",
    msgid_bugs_address="info@example.com",
    copyright_holder="My Organization"
)
run_steps(steps, "Extraction failed", "Strings extracted")
```

--------------------------------

### run_steps Function Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Example of how to use the run_steps function to execute a series of steps and display status messages.

```python
from invenio_cli.cli.utils import run_steps
from invenio_cli.commands import InstallCommands

commands = InstallCommands(config)
steps = commands.install(pre=True, dev=True)
run_steps(steps, "Installation failed", "Installation successful")
```

--------------------------------

### DockerHelper execute_cli_command Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of executing an invenio CLI command inside the web-ui container.

```python
response = helper.execute_cli_command("my-invenio", "invenio db init create")
print(response.output)
```

--------------------------------

### run_cmd example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example usage of the run_cmd function to execute a shell command and print its output.

```python
from invenio_cli.helpers.process import run_cmd

response = run_cmd(["ls", "-la"])
print(response.output)
```

--------------------------------

### Install with uv or pipenv

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/docs/contributing.md

Commands to install the local copy into a virtual environment using uv or pipenv.

```console
$ cd invenio-cli/
# with uv
$ uv venv
$ uv pip install -e ".[tests]"
# with pipenv
$ pipenv run pip install -e ".[tests]"
```

--------------------------------

### Commands Constructor Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Example of initializing the Commands class.

```python
from invenio_cli.commands import Commands
from invenio_cli.helpers.cli_config import CLIConfig

config = CLIConfig()
commands = Commands(config)
```

--------------------------------

### Files Section Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of the [files] section in .invenio, mapping project files to template paths.

```ini
[files]
invenio.cfg = templates/invenio.cfg
docker-compose.yml = templates/docker-compose.yml
# ... more tracked files
```

--------------------------------

### combine_decorators Function Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Example demonstrating how to combine Click decorators using combine_decorators.

```python
options = combine_decorators(
    click.option("--verbose", "-v", is_flag=True),
    click.option("--quiet", "-q", is_flag=True)
)

@click.command()
@options
def cmd(verbose, quiet):
    pass
```

--------------------------------

### handle_process_response Function Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Example of how to use handle_process_response to manage the outcome of a process.

```python
response = run_cmd(["docker", "--version"])
handle_process_response(response, fail_message="Docker not installed")
```

--------------------------------

### Bash example for translations extract

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example of running the translations extract command, which prompts for necessary options.

```bash
invenio-cli translations extract
# Prompts for each option
```

--------------------------------

### FunctionStep example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of creating and using a FunctionStep to execute a custom Python function.

```python
from invenio_cli.commands.steps import FunctionStep

def update_config(path):
    # ... custom logic
    return ProcessResponse(status_code=0)

step = FunctionStep(
    func=update_config,
    args={"path": "/tmp/config"},
    message="Updating configuration..."
)
```

--------------------------------

### CookiecutterWrapper get_replay Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of retrieving user input from cookiecutter's replay file.

```python
wrapper = CookiecutterWrapper("RDM")
project_dir = wrapper.cookiecutter()
replay = wrapper.get_replay()
author = replay['cookiecutter']['author_name']
```

--------------------------------

### install_packages Method

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Installs Python packages as editable installs.

```python
def install_packages(self, packages: list[str], log_file: str = None) -> list[CommandStep]
```

--------------------------------

### Minimal .invenio configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of a minimal .invenio configuration file, specifying flavor, log file, and project details.

```ini
[cli]
flavour = RDM
logfile = /logs/invenio-cli.log

[cookiecutter]
project_name = My Invenio
project_shortname = my-invenio
author_name = Jane Developer
author_email = jane@institution.edu
database = postgresql
search = elasticsearch7
file_storage = local
```

--------------------------------

### Recovery for Dependency Installation Failed

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/errors.md

Commands to clear caches and retry dependency installation.

```bash
# Clear caches
pipenv clean        # for pipenv
rm -rf .venv        # for uv
rm -rf node_modules # for npm/pnpm

# Retry installation
invenio-cli install --pre --dev
```

--------------------------------

### env context manager example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/helpers.md

Example of using the env context manager to set environment variables for a specific block of code.

```python
from invenio_cli.helpers.env import env

with env(FLASK_DEBUG="1", VERBOSE="true"):
    # FLASK_DEBUG and VERBOSE are set
    run_command()
    
# Original environment restored
```

--------------------------------

### Python Package Manager Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-config.md

Retrieves the Python package manager instance and demonstrates running a command.

```python
config = CLIConfig()
pkg_mgr = config.python_package_manager
cmd = pkg_mgr.run_command("invenio", "shell")
```

--------------------------------

### AssetsCommands.build_assets Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example of how to use the build_assets method to create production-ready assets. It returns a ProcessResponse indicating success or failure.

```python
response = commands.build_assets()
if response.status_code == 0:
    print("Assets built successfully")
```

--------------------------------

### Click UsageError Examples

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/errors.md

Examples of invalid commands that would trigger Click's UsageError.

```bash
invenio-cli init invalid-flavor  # Invalid choice
invenio-cli run --port not-a-number  # Invalid option type
```

--------------------------------

### install_assets

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Build and install front-end assets.

```python
def install_assets(self, debug: bool = False) -> list[Step]
```

--------------------------------

### pyshell

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Starts interactive Python shell with Flask app context.

```bash
invenio-cli pyshell [OPTIONS]
```

```python
invenio-cli pyshell
>>> app
<Flask 'invenio_app_rdm.app'>
>>> app.config['SITE_NAME']
'My Site'
```

--------------------------------

### Get more help

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Display the help message for the invenio-cli tool.

```console
# Get more help
$ invenio-cli --help
```

--------------------------------

### Install local copy with uv

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/CONTRIBUTING.rst

Command to install the local copy of invenio-cli using the uv tool within a virtual environment.

```console
$ cd invenio-cli/
# with uv
$ uv venv
$ uv pip install -e ".[tests]"
```

--------------------------------

### Initialize a New Project

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/INDEX.md

Example of initializing a new Invenio project using the invenio-cli Python API and CLI.

```python
from invenio_cli.helpers.cookiecutter_wrapper import CookiecutterWrapper
from invenio_cli.helpers.cli_config import CLIConfig

# Generate project from template
wrapper = CookiecutterWrapper("RDM")
project_dir = wrapper.cookiecutter()
replay = wrapper.get_replay()

# Create configuration
CLIConfig.write(project_dir, "RDM", replay)
```

```bash
invenio-cli init rdm
```

--------------------------------

### CLI assets link Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example of how to use the CLI command to link a custom module into the asset pipeline. It demonstrates linking a module and optionally watching it for changes after linking.

```bash
invenio-cli assets link ./my-invenio-module
invenio-cli assets link ./my-invenio-module --watch
```

--------------------------------

### Package Management: packages update

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Update all installed packages.

```bash
invenio-cli packages update
```

--------------------------------

### Install local copy with pipenv

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/CONTRIBUTING.rst

Command to install the local copy of invenio-cli using pipenv within a virtual environment.

```console
$ cd invenio-cli/
# with pipenv
$ pipenv run pip install -e ".[tests]"
```

--------------------------------

### Workflow Example: Adding a New Language

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Steps to add a new language to the project, including extracting strings, initializing the catalog, compiling, and verifying in the running app.

```bash
# 1. Extract strings from updated code
invenio-cli translations extract

# 2. Initialize German catalog
invenio-cli translations init --locale de

# 3. [Translator edits messages.po files]

# 4. Compile for deployment
invenio-cli translations compile

# 5. Verify in running app
invenio-cli run
# Visit app and switch language to Deutsch
```

--------------------------------

### CLI assets watch Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example of how to use the CLI command to watch for changes in JavaScript and CSS source files and rebuild assets automatically. It shows both default and custom module watching.

```bash
# Watch default assets
invenio-cli assets watch

# Watch custom module
invenio-cli assets watch --module ../my-module
```

--------------------------------

### shell

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Starts an interactive shell in the Python virtual environment.

```bash
invenio-cli shell
```

```bash
invenio-cli shell
(invenio) $ pip list
```

--------------------------------

### Wait for processes

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/INDEX.md

Example of waiting for multiple processes to complete.

```python
for proc in processes:
    proc.wait()
```

```bash
invenio-cli run
```

--------------------------------

### Exit Codes Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/errors.md

Bash commands demonstrating how to check exit codes after running Invenio CLI commands.

```bash
invenio-cli install
echo $?  # Prints 0 (success) or 1 (failure)

invenio-cli run --invalid-option
echo $?  # Prints 2 (usage error)
```

--------------------------------

### instance_path configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Absolute path to Flask instance directory. Set by `InstallCommands.update_instance_path()` after installation. Required for most operations.

```ini
[cli]
instance_path = /workspace/venv/var/instance
```

--------------------------------

### Cookiecutter Project Name Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of setting the project_name in the .invenio cookiecutter configuration.

```ini
[cookiecutter]
project_name = My Research Data Repository
```

--------------------------------

### services_expected_status

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Verify services setup status matches expectation.

```python
def services_expected_status(self, expected: bool) -> ProcessResponse
```

--------------------------------

### Custom Package Manager configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of a configuration file specifying custom Python and JavaScript package managers.

```ini
[cli]
flavour = RDM
python_package_manager = uv
javascript_package_manager = pnpm
```

--------------------------------

### Cookiecutter Database Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of setting the database type in the .invenio cookiecutter configuration.

```ini
[cookiecutter]
database = postgresql
```

--------------------------------

### Initialize environment and cd into <created folder>

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Initialize a new InvenioRDM instance and navigate into the created directory.

```console
# Initialize environment and cd into <created folder>
$ invenio-cli init rdm
$ cd <created folder>
```

--------------------------------

### Production Build for Assets

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Builds optimized assets for production, installs dependencies, and prepares for deployment.

```bash
# 1. Install dependencies (no watch)
npm install

# 2. Build optimized assets
invenio-cli assets build

# 3. Deploy
docker build -t my-invenio:latest .
docker run my-invenio:latest
```

--------------------------------

### Cookiecutter Project Short Name Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of setting the project_shortname in the .invenio cookiecutter configuration.

```ini
[cookiecutter]
project_shortname = my-rdm
```

--------------------------------

### Cookiecutter Search Backend Configuration (v10+)

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of setting the search backend in the .invenio cookiecutter configuration for newer versions.

```ini
[cookiecutter]
search = elasticsearch7
```

--------------------------------

### ensure_containers_running

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Start and health-check Docker containers (PostgreSQL/MySQL, Elasticsearch, Redis).

```python
def ensure_containers_running(self) -> ProcessResponse
```

```python
services = ServicesCommands(config)
response = services.ensure_containers_running()
if response.status_code != 0:
    print(f"Failed to start services: {response.error}")
```

--------------------------------

### Cookiecutter File Storage Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of setting the file_storage backend in the .invenio cookiecutter configuration.

```ini
[cookiecutter]
file_storage = local
```

--------------------------------

### Fix for Missing '.invenio' file

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/errors.md

Command to initialize the project if the '.invenio' file is missing.

```bash
cd /path/to/project or invenio-cli init rdm
```

--------------------------------

### Run tests

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/CONTRIBUTING.rst

Command to run tests, including code style and documentation checks, for the local development setup.

```console
$ (venv) ./run-tests.sh
```

--------------------------------

### Cookiecutter Search Backend Configuration (v9)

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of setting the search backend in the .invenio cookiecutter configuration for older versions (v9).

```ini
[cookiecutter]
elasticsearch = 7
```

--------------------------------

### Project Initialization: init

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Initializes a new Invenio project from a cookiecutter template.

```bash
invenio-cli init [FLAVOUR] [OPTIONS]
```

--------------------------------

### Commands.destroy() Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Example of generating steps to destroy the virtual environment.

```python
steps = commands.destroy()
for step in steps:
    print(f"Will execute: {step.message}")
```

--------------------------------

### assets build

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Builds assets for production.

```bash
invenio-cli assets build [OPTIONS]
```

--------------------------------

### Load configuration programmatically

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Python code demonstrating how to load and access Invenio CLI configuration settings.

```python
from invenio_cli.helpers.cli_config import CLIConfig

# Load from current directory
config = CLIConfig()

# Load from specific directory
config = CLIConfig("/path/to/project")

# Access settings
project = config.get_project_shortname()
db = config.get_db_type()
search = config.get_search_type()
host = config.get_web_host()
port = config.get_web_port()

# Get package managers
pkg_mgr = config.python_package_manager
js_mgr = config.javascript_package_manager

# Get paths
project_dir = config.get_project_dir()
instance = config.get_instance_path()

# Check service status
is_setup = config.get_services_setup()
```

--------------------------------

### services_setup configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Whether database, indices, and roles are initialized. String representation of boolean ("True" or "False"). Set by `ServicesCommands.setup()`.

```ini
[cli]
services_setup = False
```

--------------------------------

### Services and Containers: services clean

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Flush cache, destroy database, clear indices, and purge queues.

```bash
invenio-cli services clean
```

--------------------------------

### init Method

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Initializes a new language catalog.

```python
def init(self, output_dir: str, input_file: str, locale: str) -> list[CommandStep]
```

--------------------------------

### AssetsCommands.watch_assets Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example of how to use the watch_assets method to automatically rebuild assets when source files change. This method blocks indefinitely until interrupted.

```python
from invenio_cli.commands import AssetsCommands

commands = AssetsCommands(config)
response = commands.watch_assets()
# Blocks indefinitely until Ctrl+C
```

--------------------------------

### AssetsCommands.link_module Example

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Example of how to use the link_module method to integrate a custom JavaScript module into the asset pipeline. It checks the response status code for errors.

```python
response = commands.link_module("../my-custom-ui-module")
if response.status_code != 0:
    print(f"Error: {response.error}")
```

--------------------------------

### check-requirements

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Verifies system meets pre-requisites (Docker, Python, Node.js).

```bash
invenio-cli check-requirements [OPTIONS]
```

```bash
invenio-cli check-requirements --development
```

--------------------------------

### run worker

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Starts Celery worker only.

```bash
invenio-cli run worker [OPTIONS]
```

--------------------------------

### NPM Linking Steps

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Steps for linking NPM modules, including building and linking the dist folder, global linking, and linking to assets.

```bash
# 1. npm run link-dist — build and link dist folder
# 2. npm link — link module globally
# 3. npm link my-module — link in assets
```

--------------------------------

### Run the server

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Run the InvenioRDM development server.

```console
# Run the server
$ invenio-cli run
```

--------------------------------

### install_py_dependencies

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Install Python dependencies from lock file.

```python
def install_py_dependencies(self, pre: bool, dev: bool = False) -> list[Step]
```

--------------------------------

### Fix for Dependency Errors (pip install)

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/errors.md

Command to purge pip cache.

```bash
pip cache purge
```

--------------------------------

### upgrade

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Upgrades instance to a newer version using a custom migration script.

```bash
invenio-cli upgrade --script <PATH>
```

```bash
invenio-cli upgrade --script ./migrations/v10_to_v11.py
```

--------------------------------

### install_locked_dependencies Method

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/commands.md

Installs dependencies from an existing lock file.

```python
def install_locked_dependencies(self, pre: bool, dev: bool) -> list[CommandStep]
```

--------------------------------

### Containerized 'Production' environment - Spin-up InvenioRDM

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/docs/index.md

Spin up the InvenioRDM instance using containers.

```console
# Spin-up InvenioRDM
$ invenio-cli containerize
```

--------------------------------

### Manage Dependencies Programmatically

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/INDEX.md

Programmatically lock dependencies and install from a lock file.

```python
from invenio_cli.helpers.cli_config import CLIConfig
from invenio_cli.commands import PackagesCommands
from invenio_cli.cli.utils import run_steps

config = CLIConfig()
commands = PackagesCommands(config)

# Lock dependencies
steps = commands.lock(pre=True, dev=True)
run_steps(steps, "Locking failed", "Dependencies locked")

# Install from lock file
steps = commands.install_locked_dependencies(pre=True, dev=True)
run_steps(steps, "Installation failed", "Installed successfully")
```

```bash
invenio-cli packages lock --pre --dev
invenio-cli packages install
```

--------------------------------

### Fix for Service Startup Errors

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/errors.md

Commands to restart Invenio services.

```bash
docker-compose down -v && invenio-cli services start
```

--------------------------------

### Cookiecutter Author Email Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of setting the author_email in the .invenio cookiecutter configuration.

```ini
[cookiecutter]
author_email = john@example.com
```

--------------------------------

### Cookiecutter Author Name Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Example of setting the author_name in the .invenio cookiecutter configuration.

```ini
[cookiecutter]
author_name = John Doe
```

--------------------------------

### Handling CalledProcessError in Python

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/errors.md

Example of using `run_interactive` and checking the response status code.

```python
from invenio_cli.helpers.process import run_interactive

response = run_interactive(command)
if response.status_code != 0:
    # Error occurred
    print(f"Command failed: {command}")
```

--------------------------------

### Optional: add demo data (containers)

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Optionally add demo data when using the containerized environment.

```console
# Optional: add demo data
$ invenio-cli demo --containers
```

--------------------------------

### Add demo data

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Optionally add demo data to the local development environment.

```console
# Optional: add demo data
$ invenio-cli demo --local
```

--------------------------------

### Spin-up InvenioRDM

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Spin up the InvenioRDM instance using containers.

```console
# Initialize environment and cd into <created folder>
$ invenio-cli init rdm
$ cd <created folder>

# Spin-up InvenioRDM
$ invenio-cli containerize
```

--------------------------------

### Handle Configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/INDEX.md

Programmatically access project configuration settings and package managers.

```python
from invenio_cli.helpers.cli_config import CLIConfig
from invenio_cli.errors import InvenioCLIConfigError

try:
    config = CLIConfig()
    
    # Access settings
    shortname = config.get_project_shortname()
    db_type = config.get_db_type()
    instance_path = config.get_instance_path()
    
    # Access package managers
    pkg_mgr = config.python_package_manager
    js_mgr = config.javascript_package_manager
    
except InvenioCLIConfigError as e:
    print(f"Configuration error: {e}")
    # Likely not in project directory or missing .invenio
```

--------------------------------

### Bash command for translations init

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

CLI command to initialize a catalog for a new language.

```bash
invenio-cli translations init [OPTIONS]
```

--------------------------------

### Package Management: packages outdated

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

List outdated packages.

```bash
invenio-cli packages outdated
```

--------------------------------

### Services and Containers: containers clean

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Clean services (cache, database, indices) inside containers.

```bash
invenio-cli containers clean
```

--------------------------------

### assets watch

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/cli-commands.md

Watches source files for changes and rebuilds assets.

```bash
invenio-cli assets watch [OPTIONS]
```

--------------------------------

### logfile configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Path to CLI log file (relative to project)

```ini
[cli]
logfile = /logs/invenio-cli.log
```

--------------------------------

### PNPM Linking Steps

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/api-reference/assets-translations.md

Steps for linking PNPM modules, including preparing for linking, linking to assets directly, and finalizing the process.

```bash
# 1. pnpm prelink-dist — prepare for linking
# 2. pnpm link — link to assets directly
# 3. pnpm postlink-dist — finalize
```

--------------------------------

### flavour configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Project flavor: "RDM" or "ILS"

```ini
[cli]
flavour = RDM
```

--------------------------------

### Update configuration programmatically

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Python code demonstrating how to update Invenio CLI configuration settings.

```python
# Update instance path
config.update_instance_path("/new/path")

# Mark services as initialized
config.update_services_setup(True)
```

--------------------------------

### Containerized deployment without JS installation

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/README.rst

Deploy the containerized InvenioRDM instance without reinstalling JavaScript dependencies, useful after code updates.

```console
# After updating statics or code, if you do not need to re-install JS
# dependencies which can take time
$ invenio-cli containerize --no-install-js
```

--------------------------------

### web_host configuration

Source: https://github.com/inveniosoftware/invenio-cli/blob/master/_autodocs/configuration.md

Web server bind address. Used by `CLIConfig.get_web_host()`. Override for local network access.

```ini
[cli]
web_host = 0.0.0.0
```