Admin CLI

The Journiv Admin CLI provides a powerful set of tools for system administration tasks that are difficult to perform through the web interface.

Usage

The Admin CLI is included in the standard Journiv Docker image. You don't need to install anything extra; you just need to run it from your server's shell.

There are three primary ways to interact with the CLI:

1. In a Running Container (Recommended for Quick Tasks)

Best for quick operations like password resets or version checks.

# Recommended
docker compose exec app ./journiv-admin [command] [options]

# Alternative
docker compose exec app python -m app.cli [command] [options]

Example:

docker compose exec app ./journiv-admin auth change-password -e admin@example.com

2. Using a Dedicated Admin Container (Recommended for Large Imports)

For long-running operations like large imports, we recommend starting a dedicated container. This ensures your main application remains responsive and avoids interference.

# Start the dedicated admin container
docker compose --profile admin up -d admin-cli

# Run your CLI command
docker compose exec admin-cli ./journiv-admin import import-data /data/export.zip -u admin@example.com

# Stop the container when finished
docker compose --profile admin down admin-cli

3. One-off Container

Run a command in a temporary container that is automatically removed after execution.

docker compose run --rm app ./journiv-admin [command] [options]

Management Commands

Import Data

The CLI can import large data files directly from the server's filesystem, bypassing typical web upload limits.

python -m app.cli import import-data [FILE] --user-email EMAIL [OPTIONS]

Arguments & Options

• FILE: The absolute path to your import ZIP file inside the container.
• --user-email, -u: The account email to import data for.
• --source-type, -s: Either journiv (default) or dayone.
• --dry-run: Validates the file and runs pre-flight checks without actually modifying the database.
• --force: Force the import even if critical pre-flight checks fail.
• --skip-preflight: Skips all pre-flight checks entirely (use with caution).
• --verbose, -v: Enables detailed logging (written to files).

Authentication

Manage user accounts and recover lost access.

Change Password

Reset any user's password. If you omit the --password flag, you will be prompted to enter it securely.

# Interactive (Recommended - password won't show in history)
python -m app.cli auth change-password --email admin@example.com

# Direct (Less secure)
python -m app.cli auth change-password --email admin@example.com --password newsecurepass123

Pre-Flight Checks

Before performing large operations, the CLI runs a suite of "Pre-Flight Checks" to ensure the import will succeed.

You can bypass these checks using the --force flag (proceeds despite critical failures) or --skip-preflight (disables the check suite entirely).

Feature Highlight: Efficient Imports

The CLI is heavily optimized for processing massive journals:

• Streaming Extraction: Extracts files one-by-one to keep memory usage low (O(largest file) instead of O(total size)).
• Progress Tracking: Features real-time progress bars for both extraction and database import.
• Graceful Interruption: Pressing Ctrl+C once will trigger a graceful shutdown, completing the current item and cleaning up temporary files before exiting.

Troubleshooting

"User not found"

Ensure the email exactly matches the one used in the web UI.

"Insufficient disk space"

The CLI is conservative. It requires space for the original ZIP, the extracted files, and the database overhead. If you are certain you have enough space, you can use the --force flag.

Permission Denied

All CLI commands run as appuser (UID 1000) inside the container. If you manually copied files into the volumes, ensure they are readable by this user:

sudo chown 1000:1000 /path/to/vols/journiv_app_data/_data/import.zip

Logging

Detailed DEBUG logs are automatically saved to /data/logs/cli_[command]_[timestamp].log. If a command fails, check these files for full stack traces.