Use the Oblive CLI

The oblive command is the control panel for the Oblive installation on your computer. Use it to start the product, check whether every service is healthy, read logs, update to a new release, and manage authentication or configuration. You do not need a source checkout or development tools.

The installer normally places the command at ~/.local/bin/oblive and the installation at ~/.oblive. If your shell cannot find oblive immediately after installation, run the PATH command printed by the installer or open a new terminal.

The Commands You Will Use Most

Run oblive --help for the complete command list or oblive help <command> for help with one command. For example:

oblive help logs
oblive help update

Start and Stop Oblive

Start the complete stack with:

oblive start

Oblive prepares the saved configuration, pulls the images for the installed release, starts the services, waits for them to become ready, and then opens the product in your browser. To start it without opening a browser:

oblive start --no-open

Stop or restart it with:

oblive stop
oblive restart

Normal stops and restarts preserve your database, files, configuration, and agent state. Starting Oblive also keeps the currently installed version; it never updates in the background.

Check Whether Everything Is Working

Use doctor when Oblive does not start or before collecting logs:

oblive doctor

It checks Docker and Docker Compose, the installed release files, your saved configuration, and the selected authentication method. A successful result means the installation is ready to start; it does not mean the services are already running.

Use status to see the running services:

oblive status

The migration service may show as completed rather than running. That is expected: it applies any required database changes before the rest of Oblive starts, then exits.

Read Logs

Show the latest 200 lines from all services:

oblive logs

Follow new messages as they arrive, or focus on one service:

oblive logs --follow
oblive logs backend
oblive logs --follow agent-worker

Press Ctrl+C to stop following logs. Common service names are backend, frontend, agent-chat, and agent-worker. See the Command Reference for the full allowlist.

Manage Authentication

Check the configured authentication source with:

oblive auth status

The default local mode uses the Codex login on your computer. Start or refresh that login with:

oblive auth login

If the installation uses API-key mode, auth status checks that the configured environment variable is available. API-key mode has no CLI login command; export the variable in the terminal before running oblive doctor, oblive start, or oblive restart.

For setup and security details, see Authentication and Secrets.

View or Change Configuration

Find the configuration file, open it in your terminal editor, or validate it with:

oblive config path
oblive config edit
oblive config check

Only edit local-stack.json. The files under .runtime/ are generated from it and can change the next time Oblive starts. Run oblive config check after an edit; it validates both the settings and the resulting service layout without starting the stack.

The Local Stack Configuration page explains every setting.

Update Oblive

Check the installed version first:

oblive version
oblive update

For a normal installation on the latest channel, oblive update downloads and verifies the current stable bundle, checks it with your existing configuration, and updates the whole stack as one coordinated release. If Oblive is running, the command stops it, installs the update, and starts it again. Configuration and Docker data volumes are preserved.

A version-pinned installation does not move when you run plain oblive update. Choose a release or return to the stable channel explicitly:

oblive update --version v1.3.0
oblive update --latest

Oblive rejects downgrades because a newer release may already have applied an irreversible database migration. Starting or restarting never performs an update.

Reset or Uninstall

These commands have intentionally different effects:

Plain oblive uninstall stops the services and removes the command from its installed PATH location, but leaves the installation files and Docker volumes available for recovery or a later reinstall.

A Safe Troubleshooting Routine

When something is wrong, work through these commands in order:

oblive doctor
oblive status
oblive logs backend
oblive logs agent-chat
oblive logs agent-worker

Start with doctor because it catches host, configuration, and authentication problems before they become service errors. Use status to identify a stopped or unhealthy service, then read only that service’s logs. See Troubleshooting for symptom-specific fixes.