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

# CLI Reference

> Manage a running SlackHive install with slackhive status / start / stop / logs / update / backup / restore.

Once you've installed SlackHive, the `slackhive` command is your day-to-day control surface - simple verbs for start, stop, status, logs, update, backup, and restore.

## `slackhive status`

Show whether SlackHive is running and where.

```bash theme={null}
slackhive status
```

Reports:

* Whether the web UI is up and on which port
* Whether the runner is up and its PID
* The path to `~/.slackhive/` (data and logs)

If you see **running** but can't reach the UI, check [troubleshooting](/operations/troubleshooting).

## `slackhive logs`

Tail the runner log live.

```bash theme={null}
slackhive logs
```

Runs with `--follow` by default. Ctrl-C to stop.

The log is JSON per line. To filter to a single agent:

```bash theme={null}
slackhive logs | grep '"agent":"data-bot"'
```

The **Logs tab** in the web UI shows the same stream with level badges and search.

## `slackhive stop`

Gracefully stop SlackHive.

```bash theme={null}
slackhive stop
```

This:

1. Sends SIGTERM to the managed runner and the web server
2. Sweeps any **orphan** runner processes (e.g. an accidental `tsx watch` from a previous dev session)
3. Unlinks the `~/.slackhive/runner.lock` file

A single command cleans the whole stack. No stale processes, no manual `kill`.

## `slackhive start`

Start SlackHive.

```bash theme={null}
slackhive start
```

This:

1. Checks `~/.slackhive/runner.lock` - if another runner is alive, exits with a clear error
2. If the lock is stale (the PID isn't alive), removes it automatically
3. Picks free ports for the web and runner (default 3001 / 3002; auto-negotiates if taken)
4. Writes the new PID into the lock
5. Starts the web and runner

## `slackhive update`

Pull the latest code and rebuild.

```bash theme={null}
slackhive update
```

Rebuilds and restarts SlackHive. Your data (`~/.slackhive/data.db`) is preserved.

* **npm install (recommended):** `slackhive update` detects your install type. If you installed via npm, it will tell you to run `npm update -g slackhive` instead.
* **git clone install:** runs `git pull`, `npm install`, rebuilds the runner and web app, restarts.

If `git pull` fails (e.g. local changes), stash them first: `git stash && slackhive update`.

## `slackhive backup`

Create a database backup.

```bash theme={null}
slackhive backup
```

When SlackHive is running, the CLI asks the runner to create a consistent live snapshot. When SlackHive is stopped, the CLI copies the closed database file.

Write to a specific path:

```bash theme={null}
slackhive backup --output /secure/backups/slackhive.db
```

Default backups live in `~/.slackhive/backups/`.

## `slackhive restore`

Restore the database from a backup. Restore is CLI-only and stops SlackHive before replacing the local SQLite database.

```bash theme={null}
slackhive restore -f ~/.slackhive/backups/data-20260629-093000.db \
  --recovery-key ~/Downloads/slackhive-recovery-20260629-093100.json
slackhive start
```

The recovery-key password is prompted without echoing. For automation, set `SLACKHIVE_RECOVERY_PASSWORD` in the environment.

If you have the original `.env` instead of a recovery-key file:

```bash theme={null}
slackhive restore -f /backups/data.db --env /secure/slackhive.env
slackhive start
```

See [Backup & Recovery](/operations/backup-recovery) for the full disaster-recovery flow.

## Where data lives

| Path                                      | What it holds                                                                 |
| ----------------------------------------- | ----------------------------------------------------------------------------- |
| `~/.slackhive/data.db`                    | SQLite DB - agents, memories, skills, history, settings                       |
| `~/.slackhive/backups/`                   | SQLite backup files and pre-restore safety snapshots                          |
| `~/.slackhive/agents/<slug>/`             | Per-agent workspace (instructions, sessions, copies of assigned wiki folders) |
| `~/.slackhive/knowledge/<folderId>/wiki/` | Compiled wikis for the Knowledge Library (source of truth)                    |
| `~/.slackhive/logs/runner.log`            | Full runner log stream                                                        |
| `~/.slackhive/runner.lock`                | Singleton lock - JSON with `pid`, `startedAt`, `mode`                         |
| `~/.slackhive/slackhive.pid`              | Web-server PID file                                                           |

Use [Backup & Recovery](/operations/backup-recovery) for database backups and recovery-key export. Snapshot `~/.slackhive/` separately if you also want generated workspaces, compiled wiki files, and logs.

## Running from any directory

`slackhive` commands work from anywhere on disk - the CLI finds the install via the `apps/runner` marker. You don't need to `cd` into the repo.

## Troubleshooting

See [operations / troubleshooting](/operations/troubleshooting) for common errors and what they mean.