> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Octop Server Commands: init, run, service, and update

> Bootstrap a new install, start the server in the foreground, manage it as a system service, and update to the latest Octop release.

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.

```bash Interactive setup theme={null}
octop init
```

```bash Non-interactive setup theme={null}
octop init --admin-username admin --admin-password mypassword1 --yes
```

### Options

| Option | Env var | Description |
| - | - | - |
| `--admin-username TEXT` | `OCTOP_ADMIN_USERNAME` | Username for the first admin account |
| `--admin-password TEXT` | `OCTOP_ADMIN_PASSWORD` | Password for the first admin account |
| `--admin-display-name TEXT` | `OCTOP_ADMIN_DISPLAY_NAME` | Display name for the first admin account |
| `--force` | — | Wipe existing `~/.octop/` contents before bootstrapping |
| `--yes` | — | Skip all interactive prompts |

> [!NOTE]
>
> `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.

```bash Default theme={null}
octop run
```

```bash Custom host and port theme={null}
octop run --host 0.0.0.0 --port 8088
```

```bash HTTPS with self-signed certificate theme={null}
octop run --ssl
```

```bash HTTPS with your own certificate theme={null}
octop run --ssl --certfile /path/cert.pem --keyfile /path/key.pem
```

### Options

| Option | Default | Description |
| - | - | - |
| `--host TEXT` | `127.0.0.1` | Bind host (overrides `OCTOP_BIND_HOST`) |
| `--port INTEGER` | `8088` | Listen port (overrides `OCTOP_PORT`) |
| `--reload / --no-reload` | off | Enable uvicorn auto-reload (development only) |
| `--ssl / --no-ssl` | off | Enable HTTPS |
| `--certfile PATH` | — | TLS certificate in PEM format |
| `--keyfile PATH` | — | TLS private key in PEM format |
| `--log-level` | `info` | One of: `debug`, `info`, `warning`, `error` |

> [!WARNING]
>
> 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.

```bash Start (and install if missing) theme={null}
octop service start
```

```bash Stop theme={null}
octop service stop
```

```bash Restart theme={null}
octop service restart
```

```bash Check status and health theme={null}
octop service status
```

> [!NOTE]
>
> `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.

```bash Check and install theme={null}
octop update
```

```bash Check only, do not install theme={null}
octop update --check
```

### Options

| Option | Description |
| - | - |
| `--check / --no-check` | Report the available version without installing |
| `--channel TEXT` | Release channel to check: `pypi` (default), `testpypi`, or a custom index URL |

***

## `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.

```bash Login as admin theme={null}
octop user login --username admin
```

After a successful login, the JWT is written to `~/.octop/cli_state.json`. Delete that file or run `octop clean --state` to log out.

> [!TIP]
>
> 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.

```bash Clear CLI state only (keep data) theme={null}
octop clean --state
```

```bash Wipe the entire ~/.octop/ directory theme={null}
octop clean --all
```

```bash Skip the confirmation prompt theme={null}
octop clean --all --yes
```

### Options

| Option | Description |
| - | - |
| `--state / --all` | What to remove: `--state` clears CLI state only; `--all` wipes the entire `~/.octop/` tree |
| `--yes` | Skip the confirmation prompt |

> [!WARNING]
>
> `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).

```bash Show current CLI state theme={null}
octop config show
```

```bash Pin the default --user theme={null}
octop config set-user admin
```

### Subcommands

| Subcommand | Description |
| - | - |
| `show` | Print the current CLI state |
| `set-user` | Pin the default `--user` |

***

## `octop completion`

Generate and install shell command completion.

```bash Dump a bash completion snippet theme={null}
octop completion show bash
```

```bash Dump a zsh completion snippet theme={null}
octop completion show zsh
```

```bash Append to ~/.zshrc or ~/.bashrc theme={null}
octop completion install
```

> [!TIP]
>
> 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.

```bash theme={null}
octop version
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.