SessionDB CLI (scli) — Tooling Guide

This document is the main tooling reference for the SessionDB CLI (scli). It includes a step-by-step workflow and a troubleshooting section with common issues, how to verify them, and how to resolve or find the solution.

Table of contents

1. Step-by-step guide: Working with scli
2. Issues and solutions
3. How to find the solution for a new issue

Step-by-step guide: Working with scli

Prerequisites

• Network: GitHub access for install/update (releases from sessiondb/service, sessiondb/client, and sessiondb/scli).
• Permissions: Write access to install root (default: /opt/sessiondb as root, or ~/.local/share/sessiondb as user) and config directory (default: ~/.config/sessiondb or SESSIONDB_CONFIG_DIR).
• Optional: On Linux with systemd, systemctl for deploy/start/stop of services.

Step 1: Install scli

Choose one:

• One-liner (recommended)

  curl -sSL https://raw.githubusercontent.com/sessiondb/scli/main/install.sh | bash

  For a specific version:
  curl -sSL ... | bash -s -- v1.0.0

• Go install

  go install .
  export PATH="$PATH:$(go env GOPATH)/bin"

• Manual: Download the binary from Releases, put it on your PATH, and name it scli (or scli.exe on Windows).

Then open a new terminal or run source ~/.zshrc (or ~/.bashrc) so scli is on PATH. Verify:

scli
# Should print usage (init, install, run, ...).

Step 2: Initialize configuration

Run the interactive wizard to set database, Redis, and server options. This creates config.toml and generates .env for the backend/systemd.

scli init

• Use --config-dir DIR if you want a custom config directory (otherwise $HOME/.config/sessiondb or SESSIONDB_CONFIG_DIR).
• Secrets (DB_CREDENTIAL_ENCRYPTION_KEY, MIGRATE_TOKEN) are generated on first run and reused if config already exists.

Verify:

scli config view
# Shows config directory and main settings (and whether secrets are set).

Step 3: Install SessionDB (backend + frontend)

Download and install a SessionDB release into the install root (versions/<tag>/, current symlink).

scli install
# Or a specific version:
scli install v1.0.1

• Omit version for latest.
• Use -v or --verbose for detailed download/log output.
• Use --force to reinstall even if the version is already present (and to fetch UI binary if it was missing).

If the systemd units are already installed and active, scli install will try to restart them with the new version (on Linux, and when run as root).

Verify:

scli resources
# Shows install root, current version, paths to server binary, UI, config files, and systemd unit.

Step 4a: Run locally (no systemd)

Start the server in the background and optionally follow logs:

scli run
# Or: scli run v1.0.1
# Or: scli run v1.0.1 /path/to/workdir

• Config is read from config.toml (or .env) in the config directory.
• Ctrl+C only stops the log tail; the server keeps running. Stop it with:

scli stop

To start without following logs:

scli start
# Then: scli logs -f --component api  (or ui)

To run only API or only UI:

scli run --component api
scli run --component ui
scli run --component all

Step 4b: Deploy with systemd (bare metal)

Generate systemd unit file(s) and install them:

scli deploy --platform baremetal --output sessiondb.service

• Generates sessiondb.service (API) and sessiondb-ui.service (UI) by default (--component all). Use --component api or --component ui to generate only one.
• If .env is missing, it is generated from config.toml (or legacy config.yaml).

Then:

sudo cp sessiondb.service sessiondb-ui.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable sessiondb sessiondb-ui
sudo systemctl start sessiondb sessiondb-ui

Verify:

scli status
# Uses default URL http://localhost:8080; use --url if different.

Step 5: Run migrations

After the server is running (either via scli run/scli start or systemd):

scli migrate

• Uses MIGRATE_TOKEN from config (config.toml / .env).
• Default URL is http://localhost:8080; override with --url BASE_URL.

Step 6: Check status and logs

• Health:
  scli status (default: http://localhost:8080/health).

• Logs:

  • With systemd: scli logs -n 100 -f --component api (or ui) uses journalctl -u sessiondb / sessiondb-ui.
  • Without systemd: same command tails the run log file under the config directory.

Step 7: Restart or upgrade

• Restart (no new download)
  scli restart (or scli restart --component all). Uses same version and config.

• Upgrade to a new version
  scli install v1.0.2 (or scli install for latest). If systemd is in use and you are root, services are restarted automatically; otherwise you may need sudo systemctl restart sessiondb sessiondb-ui.

• Self-update scli
  scli update — choose one of the last 5 scli releases and replace the current binary. On Windows, the new binary is written as scli.exe.new; replace scli.exe manually after closing the terminal.

Step 8: Reset or full cleanup

• Remove installed versions only (keeps config):
  scli reset
  Removes install root’s versions/ and current (and legacy sessiondb-install under config dir).

• Remove versions and legacy config files (.env, config.yaml):
  scli reset --all
  Note: This does not remove config.toml in the current implementation; see Issues and solutions below.

• Remove everything (install root + entire config directory, including config.toml, .env, logs, pid):
  scli prune --yes
  Destructive; use only when you want a full cleanup.

Issues and solutions

Each entry describes the issue, how to check whether you’re affected, and what to do (solution or where to look for the fix).

Config / init

Install / get

Run / start / stop / restart

Deploy

Migrate / status

Reset / prune

Logs / resources

Update (self-update)

How to find the solution for a new issue

1. Reproduce and capture the exact error
   Run the failing command (e.g. scli install v1.0.0, scli migrate) and note the full error message and exit code.

2. Check config and paths

   • scli config view — confirms config directory and that secrets/settings are present.
   • scli resources — confirms install root, current version, and presence of server binary, UI, config files, and systemd unit.

3. Use verbose where available
   For install/get: scli install VERSION -v (or --verbose) to see download and extraction steps.

4. Verify environment

   • echo $SESSIONDB_CONFIG_DIR and echo $SESSIONDB_INSTALL_ROOT — must match where you ran scli init and where you expect installs.
   • On Linux with systemd: systemctl status sessiondb sessiondb-ui and journalctl -u sessiondb -n 50.

5. Match code to behavior

   • Config / paths: internal/config/env.go, internal/config/toml.go, internal/config/env_loader.go.
   • Install / get: get.go, release.go.
   • Run / start / stop: run.go, cmd_stop.go, lifecycle.go.
   • Deploy: cmd_deploy.go.
   • Migrate / status: cmd_migrate.go, cmd_status.go.
   • Reset / prune: cmd_reset.go, cmd_prune.go.

6. Documentation and issues

   • This guide: docs/tooling.md.
   • Main usage: README.md.
   • For bugs or feature requests: open an issue in the sessiondb/scli repository (or the repo that owns the failing component) with the exact error, scli config view / scli resources output (redact secrets), and steps to reproduce.

Quick reference: commands and flags

Default URLs: migrate and status use http://localhost:8080 unless overridden with --url.