`seqdesk doctor`

seqdesk doctor is a diagnostic subcommand of the seqdesk npm launcher. It walks an installed SeqDesk directory and prints a pass/warn/fail report covering the install layout, the runtime configuration, the database connection, and (if a URL is supplied) a small set of HTTP probes against the running app.

It does not modify anything. Run it as often as you like — after install, after an update, or whenever the app behaves oddly.

Usage


seqdesk doctor [--dir /path/to/seqdesk] [--url http://127.0.0.1:8000] \
  [--timeout-ms 5000] [--json] [--help]

Flag	Default	Description
`--dir`, `-d`	current directory	Installed SeqDesk directory
`--url`, `-u`	inferred from config	Running SeqDesk base URL for HTTP probes
`--timeout-ms`	`5000`	Timeout for PostgreSQL TCP and HTTP checks
`--json`	off	Print machine-readable JSON instead of text
`--help`, `-h`	—	Show usage and exit

If --url is not supplied, doctor tries to derive one from runtime.nextAuthUrl (or app.port) in seqdesk.config.json. If neither is set, the HTTP checks are skipped with a warning.

Checks

Install layout

Check	Notes
Install directory	Path resolves and exists
`package.json`	Parseable; reports `name@version`
`seqdesk.config.json`	Present and valid JSON
`start.sh`	Present and executable
`node_modules`	Present
`.next/static`	Present (warns if `.next` exists without static assets)

Runtime configuration

Read from seqdesk.config.json (runtime.* section, with flat-key fallbacks):

Check	Status logic
`runtime.databaseUrl`	Must parse as a valid PostgreSQL URL
PostgreSQL TCP	TCP connect to `host:port` from `databaseUrl` (default port `5432`)
`runtime.directUrl`	Optional; warns if missing (falls back to `databaseUrl`)
`runtime.nextAuthUrl`	Warns if missing
`runtime.nextAuthSecret`	Fails if missing
`telemetry`	Pass when `telemetry.enabled === true`, warn otherwise (informational only)

HTTP probes (when a URL is available)

Check	What it expects
`GET /api/auth/providers`	JSON response with a `credentials` provider
`GET /api/setup/status`	`configured: true` (passes); `exists: true` warns; otherwise fails

When a URL was inferred (not passed via --url), an unreachable endpoint is reported as a warn, since the app may simply not be running. When --url was passed explicitly, the same failure is reported as a fail.

Output

Text (default)


SeqDesk doctor 1.1.82
Install dir: /opt/seqdesk
App URL: http://127.0.0.1:8000

[PASS] Install directory - /opt/seqdesk
[PASS] package.json - seqdesk@1.1.82
[PASS] seqdesk.config.json - parseable
[PASS] start.sh - executable
[PASS] node_modules - present
[PASS] .next/static - present
[PASS] runtime.databaseUrl - postgresql://seqdesk@127.0.0.1:5432/seqdesk
[PASS] PostgreSQL TCP - 127.0.0.1:5432 reachable
[WARN] runtime.directUrl - missing; databaseUrl will be used as fallback
[PASS] runtime.nextAuthUrl - http://127.0.0.1:8000
[PASS] runtime.nextAuthSecret - set
[WARN] telemetry - disabled
[PASS] HTTP /api/auth/providers - credentials auth available
[PASS] HTTP /api/setup/status - database configured

Summary: 12 pass, 2 warn, 0 fail

JSON (`--json`)

The same data, structured for scripts:


{
  "version": "1.1.82",
  "installDir": "/opt/seqdesk",
  "appUrl": "http://127.0.0.1:8000",
  "checks": [
    { "name": "Install directory", "status": "pass", "detail": "/opt/seqdesk" }
  ],
  "summary": { "pass": 12, "warn": 2, "fail": 0 }
}

Exit codes

Code	Meaning
`0`	No failed checks (warnings allowed)
`1`	At least one check failed
`2`	Invalid command-line arguments

This makes doctor safe to run in CI and post-install hooks — wire it as a non-zero gate without parsing the text output.

When to run it

After a fresh install — confirm the layout is intact and the database is reachable before logging in for the first time.
After an update — see Automatic Updates. If the app fails to come back up, doctor narrows the failure to layout, DB, or HTTP.
In CI — run seqdesk doctor --json against a freshly provisioned instance to validate the install pipeline.
When troubleshooting — failures point at exact files and ports, which is usually faster than reading the app logs from scratch.

Manual install checklist

The seqdesk npm tarball ships a MANUAL_INSTALL.md checklist that walks through provisioning a fresh Linux machine, installing both with and without a hosted profile, starting the app, running doctor, verifying telemetry, and cleaning up. Use it for end-to-end manual smoke tests before relying on a new host.

seqdesk doctor