Command Line Interface (CLI)

Inboxclaw provides a command-line interface for running the server and performing maintenance or setup tasks, such as authenticating with external APIs.

The CLI is built with Click and is invoked using the inboxclaw command.

When is the inboxclaw command available?

The inboxclaw command becomes available automatically after the first run of python main.py (which sets up the virtual environment and installs dependencies). After that, you can use inboxclaw for all commands. If you haven't run the initial setup yet, see Step 1: Install.

Core Commands

status

Checks the status of the Inboxclaw system, including the systemd service, logs, healthcheck endpoint, version info, and database statistics.

Usage:

inboxclaw status [OPTIONS]

Options:

• --config TEXT: Path to the configuration file (default: config.yaml).
• --service-name TEXT: Name of the systemd service to check (default: inboxclaw).

Example:

inboxclaw status

events

Displays the latest published events from the database.

Usage:

inboxclaw events [OPTIONS]

Options:

• -n INTEGER: Number of latest published events to display (default: 10).
• --source TEXT: Filter events by source name.
• --event-type TEXT: Filter events by event type.
• -j: Output events as JSON objects.
• --config TEXT: Path to the configuration file (default: config.yaml).

Example:

# Show the last 20 published events
inboxclaw events -n 20

# Show the last 10 events from a specific source
inboxclaw events --source gmail

# Show only events of a specific type
inboxclaw events --event-type new_email

pending-events

Displays the latest pending (coalescing) events from the database.

Usage:

inboxclaw pending-events [OPTIONS]

Options:

• -n INTEGER: Number of latest pending events to display (default: 10).
• --source TEXT: Filter pending events by source name.
• --event-type TEXT: Filter pending events by event type.
• -j: Output pending events as JSON objects.
• --config TEXT: Path to the configuration file (default: config.yaml).

Example:

# Show the last 5 pending events
inboxclaw pending-events -n 5

# Show pending events for a specific source
inboxclaw pending-events --source gmail

logs

Displays the logs for the Inboxclaw service using journalctl. This is only available on Linux systems where Inboxclaw is installed as a systemd service.

Usage:

inboxclaw logs [OPTIONS]

Options:

• -n, --lines INTEGER: Number of log lines to show (default: 20).
• -f, --follow: Follow the logs in real-time.
• --service-name TEXT: Name of the systemd service (default: inboxclaw).

Example:

# Show last 50 lines and follow
inboxclaw logs -n 50 -f

restart

Restarts the Inboxclaw systemd service. This command validates the configuration file before triggering the restart to ensure the service starts correctly.

On non-Linux systems, this command will only perform configuration validation and skip the service restart.

Usage:

inboxclaw restart [OPTIONS]

Options:

• --config TEXT: Path to the configuration file to validate (default: config.yaml).
• --service-name TEXT: Name of the systemd service to restart (default: inboxclaw).
• --user: Restart as a user service (default). Does not require root.
• --system: Restart as a system-wide service (requires root).

Example:

inboxclaw restart

config

Opens the configuration file in your default editor (or a specified one). If the file is modified and saved, the CLI automatically validates the new configuration and suggests a restart if the validation passes.

Usage:

inboxclaw config [OPTIONS]

Options:

• --vim: Open the configuration in vim.
• --nano: Open the configuration in nano.

Example:

# Open in default editor
inboxclaw config

# Open in nano
inboxclaw config --nano

update

Checks the GitHub repository for updates, pulls them, and installs any new dependencies.

Usage:

inboxclaw update [OPTIONS]

Options:

• --force: Force update even if no changes are detected.

Example:

inboxclaw update

listen

Starts the Inboxclaw server. This command is the main entry point for running the application.

Usage:

inboxclaw listen [OPTIONS]

Options:

• --config TEXT: Path to the configuration file (default: config.yaml).

Example:

inboxclaw listen --config my-custom-config.yaml

subscribe

Subscribes to an SSE (Server-Sent Events) endpoint and dumps raw JSON payloads to stdout. This is useful for debugging or integrating with other tools that can consume JSON from a pipe.

Usage:

inboxclaw subscribe [OPTIONS]

Options:

• --config TEXT: Path to the configuration file (default: config.yaml).
• --sink TEXT: Specific SSE sink name to use (if multiple SSE sinks are configured).

Example:

inboxclaw subscribe

pull

Runs a pull request against a locally configured HTTP Pull sink. It extracts a batch of events and outputs the raw JSON response to stdout, making it suitable for CLI integrations.

Usage:

inboxclaw pull [OPTIONS]

Options:

• --config TEXT: Path to the configuration file (default: config.yaml).
• --name TEXT: Name of the HTTP Pull sink to use (if multiple are configured).
• --event-type TEXT: Filter by event type (supports * and .*).
• --batch-size INTEGER: Limit the number of events to extract (must be >= 1).

Example:

# Pull a batch of events
inboxclaw pull --event-type "gmail.*" --batch-size 5

# Output:
# {"batch_id": "abc-123", "events": [...], "remaining_events": 0}

pull-mark-processed

Marks a specific batch of events as processed in a locally configured HTTP Pull sink. This should be called after you have successfully processed the events returned by the pull command.

Usage:

inboxclaw pull-mark-processed [OPTIONS]

Options:

• --config TEXT: Path to the configuration file (default: config.yaml).
• --name TEXT: Name of the HTTP Pull sink to use (if multiple are configured).
• --batch-id TEXT: Required. The batch ID returned by the pull command.

Example:

inboxclaw pull-mark-processed --batch-id "abc-123"

install

Installs Inboxclaw as a systemd service on Linux. This allows the pipeline to start automatically on boot and restart if it crashes.

Additionally, it creates a symlink to the inboxclaw CLI command in your system PATH (~/.local/bin for user installations or /usr/local/bin for system-wide ones), making inboxclaw accessible from any directory outside the virtual environment.

Usage:

inboxclaw install [OPTIONS]

Options:

• --config TEXT: Path to the configuration file (default: config.yaml).
• --user: Install as a user service (default). Does not require root.
• --system: Install as a system-wide service (requires root).
• --name TEXT: Name of the systemd service (default: inboxclaw).

Examples:

User Installation (Non-root):

inboxclaw install --user

After installing as a user, you may want to enable "linger" for your user so the service starts on boot without you having to log in:

loginctl enable-linger $USER

System-wide Installation (Root):

sudo inboxclaw install --system

---

Service-Specific Commands

google

Commands for interacting with Google APIs (Gmail, Drive, Calendar).

google auth

Starts the OAuth 2.0 flow to authorize the pipeline to access your Google account. This command will open a browser for you to sign in and will save the credentials to the configured token file.

See Google Auth Guide for more details.

google list-calendars

Lists all available calendars in your Google account. This is useful for finding the calendar_id needed for the Google Calendar source.

---

nordigen

Commands for GoCardless (formerly Nordigen) Bank Account Data API.

nordigen auth

Exchanges your GoCardless API credentials (secret_id and secret_key) for a long-lived access token.

nordigen connect

Starts the process of connecting a bank account. It generates a requisition link that you must open in your browser to authorize access to your bank. Once authorized, it will display the account IDs you can add to your config.yaml.

See Nordigen Source for more information.

---

Global Options

• --help: Show the help message for any command or sub-command.

Example:

inboxclaw google auth --help