npm package: @fyresmith/hive-server
Description: Collaborative Obsidian vault server
Latest version: 5.0.0

# Hive Server

Hive server now ships with a first-class `hive` operations CLI for install, setup, tunnel management, env management, and service lifecycle.

## Install

```bash
npm i -g hive-server
```

The global install exposes:

```bash
hive --help
```

To build/verify the current local checkout and install it globally:

```bash
npm run install-hive
```

## Release System (GitHub Actions + npm)

This repo now includes a release pipeline for `hive-server`:

- CI: `.github/workflows/hive-server-ci.yml`
- Release tag workflow: `.github/workflows/hive-server-release-tag.yml`
- npm publish workflow: `.github/workflows/hive-server-publish.yml`

### One-time repo setup

Configure npm Trusted Publisher for this repo/workflow:

- Package: `hive-server`
- Provider: GitHub Actions
- Repository: this repository
- Workflow file: `.github/workflows/hive-server-publish.yml`
- GitHub Actions publish job should run Node 24+ (already configured in workflow)

No `NPM_TOKEN` secret is required when Trusted Publishing is configured.

### How releases work

1. Run workflow `hive-server-release-tag` from the default branch.
2. Choose release type (`patch|minor|major|prerelease|custom`).
3. Workflow bumps `package.json`, commits, and pushes tag `hive-server-vX.Y.Z`.
4. Tag push triggers `hive-server-publish`, which:
    - verifies the package
    - checks tag version matches `package.json`
    - publishes to npm with provenance
    - creates a GitHub Release with generated notes

## Fast Path

Run the guided setup:

```bash
hive setup
```

Non-interactive defaults:

```bash
hive setup --yes
```

`hive setup` can:

- initialize and validate `.env`
- generate a new vault folder from a parent location you choose
- configure Cloudflare Tunnel
- install Hive as a launchd/systemd service
- run post-setup checks

`hive dashboard` can start in setup mode even before `VAULT_PATH` is configured, so first-time setup can be completed in the browser.

## Config and Env

Operator config:

- `~/.hive/config.json`

Default env location:

- `~/.hive/server/.env`

Env commands:

```bash
hive env init
hive env edit
hive env check
hive env print
```

Managed mode owner identity is persisted in managed state during setup. No owner ID env field is required.

Managed operations:

```bash
hive managed status
hive managed invite create
hive managed invite list
hive managed invite revoke <code>
hive managed member list
hive managed member remove <userId>
```

### Invite Onboarding

Invite-first download onboarding is the default behavior:

1. Owner creates invite via `hive managed invite create`.
2. Recipient opens claim URL, signs in/creates an account, and claims invite.
3. Recipient downloads a preconfigured managed-vault package zip.
4. Recipient opens extracted folder in Obsidian; Hive performs bootstrap token exchange and initial sync.

Optional env overrides:

- `HIVE_BUNDLE_GRANT_TTL_MINUTES` (default `15`)
- `HIVE_BOOTSTRAP_TOKEN_TTL_HOURS` (default `24`)
- `HIVE_BUNDLE_DENY_PATHS` (comma-separated deny list for bundle policy)

## Tunnel Operations

```bash
hive tunnel setup
hive tunnel status
hive tunnel run
hive tunnel service-install
hive tunnel service-status
```

## Server Service Operations

```bash
hive service install
hive service start
hive service stop
hive service restart
hive service status
hive service logs
hive service uninstall
```

## Runtime and Diagnostics

Run directly in foreground:

```bash
hive run
```

Diagnostics:

```bash
hive up
hive down
hive logs
hive doctor
hive status
hive update
```

`hive up` / `hive down` start or stop installed Hive and cloudflared services together.
`hive logs` streams service logs (`--component hive|tunnel|both`).
`hive update` installs the latest npm release for the current package and then restarts the Hive OS service and cloudflared service when they are installed.