Skip to main content
These commands control the Octop server lifecycle — bootstrapping a fresh install, starting the server process, registering it as a system service, and keeping it up to date. Run them in order the first time you set up Octop, and return to them whenever you need to manage or upgrade your deployment.

​
octop init

Bootstrap ~/.octop/ with the SQLite database, JWT secret, and first admin account. Run this once before starting the server for the first time.

​
Options

octop init is idempotent on the database — running it again on an existing install is safe and only applies missing migrations. Use --force to wipe ~/.octop/ and start completely fresh.

​
octop run

Start the Octop server in the foreground using uvicorn. This serves the web UI, HTTP/SSE API, and IM channel listeners on a single process.

​
Options

Do not use --reload in production. Auto-reload restarts the process on every file change and is intended for local development only.

​
octop service

Register Octop as a system service so it starts automatically on boot and runs in the background.
octop service auto-detects the platform: it uses systemd on Linux and launchd on macOS. The status subcommand probes the HTTP health endpoint and prints journal or log hints on failure. Force the scope with --scope user or --scope system (or via OCTOP_SERVICE_SCOPE). On Linux, start and restart install a systemd drop-in (octop.service.d/10-nofile.conf) with LimitNOFILE=65535. The main unit file is not rewritten unless it is missing or you pass --force-install. To undo: delete the drop-in, then systemctl daemon-reload && systemctl restart octop.

​
octop update

Check for a newer Octop release on PyPI and install it automatically.

​
Options

​
octop user login

Attach the CLI to a running server by exchanging credentials for a JWT. The token is stored in ~/.octop/cli_state.json so that Attach-mode commands (channel test, models ollama-*, etc.) can reach the server without re-authenticating.
After a successful login, the JWT is written to ~/.octop/cli_state.json. Delete that file or run octop clean --state to log out.
All other octop user subcommands (create, list, passwd, role, disable, delete) operate directly against the local SQLite database and do not require a running server or a prior login.

​
octop clean

Reset CLI state or wipe the entire ~/.octop/ tree. Destructive — read the help carefully before running.

​
Options

octop clean --all deletes the database, workspaces, and all configuration. Run octop backup create before using this command.

​
octop config

Inspect or edit ~/.octop/cli_state.json (default base URL, user, agent).

​
Subcommands

​
octop completion

Generate and install shell command completion.
After running octop completion install, reopen your terminal or run source ~/.zshrc (or source ~/.bashrc) to enable completion.

​
octop version

Print the installed octop version. Equivalent to the global -v, --version flag.