Admin CLI

Overview

The crewship admin command group is the operator-on-the-host recovery surface. Every subcommand here runs a direct write against the local SQLite database, intentionally bypassing the HTTP API. The model is the same one GitLab (gitlab-rake gitlab:password:reset), Gitea (gitea admin user change-password), Nextcloud (occ user:resetpassword) and Mattermost (mmctl user change-password) all adopt: shell access to the host is the credential. If you can ssh to the box, you are the admin — no second authentication factor would be meaningful, since you already control the data directory and could rewrite the database manually anyway. The flow is deliberately non-circular. The most important caller is an admin whose account is locked out and whose server may or may not be running — routing recovery through the same server they’re recovering would be a chicken-and-egg failure. crewship admin therefore opens ~/.crewship/crewship.db directly (or whatever CREWSHIP_DATA_DIR / DATABASE_URL points at), runs the requested SQL — the mutating commands in a transaction — and exits. The HTTP layer never sees the request and the auth middleware never runs.

Because the write happens straight against SQLite, an admin-CLI action does not produce a journal_entries row the way HTTP-fronted actions do — it never passes through the audit middleware. Treat these commands as out-of-band operator actions and record them in your own change log if you need an audit trail.

Five verbs ship today, all in cmd/crewship/cmd_admin.go. reset-password mints a fresh bcrypt hash for a user (interactive prompt by default; --password for scripted recovery; --password-stdin for the leak-free CI pattern that mirrors docker login --password-stdin) and revokes every active session in the same transaction so a leaked cookie can’t outlive the recovery. invalidate-sessions is the same session-revoke without a password rotation — use when the password is believed safe but a session token is suspected leaked. list-users dumps every row of the users table to a tab-aligned table, flags currently-locked-out accounts with a footer count, accepts --locked-only to filter, and shows the per-account failed_login_count. promote rewrites a user’s workspace role (OWNER / ADMIN / MANAGER / MEMBER / VIEWER), accepting --workspace=<slug> or defaulting to the user’s single workspace when there’s exactly one. sessions list is a forensic read-only dump of every user_sessions row for --email=<email> (--active-only to filter, --limit to cap) — the read side paired with invalidate-sessions. Each opens the DB with a 30s busy_timeout, so a write that races the running server serializes rather than failing instantly; still, stop the server first to avoid a half-applied change.

When to use it

Reach for crewship admin only when the in-band recovery paths can’t apply. For everyday user management — invites, role changes on a healthy server, password rotation from inside the app — the web UI is the right surface; bypassing it leaves the audit trail thinner and risks racing the running server. The narrow set of legitimate uses:

You can’t log in at all. Forgot password, sole owner of the workspace, mailer not configured, OAuth provider misconfigured — any combination where the web /forgot flow won’t deliver a reset link. crewship admin reset-password --email=… mints a new hash directly.
The mailer is unreachable or never set up. Fresh self-hosted installs without RESEND_API_KEY get a deliberate mailer.Disabled — /forgot still returns 200 (no enumeration) but no email goes out. Use the CLI instead of standing up SMTP just to recover one account.
CI / unattended provisioning needs a seeded admin. A Dockerfile that bakes a baseline workspace can run crewship admin reset-password --email=admin@example.com --password=$BOOTSTRAP_PASSWORD non-interactively against the freshly migrated database, then start the server. The HTTP API isn’t available yet at that point, so this is the only path.
You need to verify which email actually exists. Operators routinely guess at email casing (Admin@… vs admin@…) before a reset. crewship admin list-users dumps the table so the reset command targets the right row instead of silently failing.
A botched RBAC change locked everyone out of a workspace. If a promote from the UI accidentally demoted the last OWNER, the UI can no longer fix it (no OWNER left to call the endpoint). Re-promoting from the CLI is the unblock.
You suspect a session token leak but the password is fine. Stolen laptop recovered, browser history dumped to a chat, a tester pasted a session cookie in a screenshot — crewship admin invalidate-sessions --email=… force-logs the user from every device without forcing a password rotation. The user can log back in normally on the next attempt; only the cached cookies on the lost devices stop working.
Periodic compliance sweep. Audit guidance that says “log every operator out at the end of the quarter” maps to a one-shot invalidate-sessions per user; same audit row shape as the leaked-token response (revoked_reason='admin_invalidate').

If the server is healthy, the user is logged in, and the workspace still has at least one OWNER, prefer the corresponding HTTP endpoint or settings page — every admin-CLI call is one more uncontrolled DB write to keep out of the audit story.

Key concepts

Term	What it means here
Data directory	The directory holding `crewship.db` and adjacent state. Defaults to `~/.crewship`; overridable via `CREWSHIP_DATA_DIR`. A `DATABASE_URL` env var takes precedence over both and points the admin CLI straight at a DSN. If the resolved database file is missing the command aborts before any SQL runs.
Bcrypt hash	The on-disk form of a user password. Stored in `users.hashed_password`; admin `reset-password` calls `bcrypt.GenerateFromPassword` with cost factor 12, so a hash written by the CLI is indistinguishable from one minted by the web signup flow.
Workspace role	Persisted in the `workspace_members` table per `(workspace_id, user_id)`. `promote` accepts `OWNER`, `ADMIN`, `MANAGER`, `MEMBER`, or `VIEWER`. `OWNER` is the only role that can delete a workspace or demote another `OWNER`.
`--workspace` resolution	If the user belongs to exactly one workspace, `promote` infers it. If they belong to multiple, the flag is required and a clear error (`user belongs to multiple workspaces — pass --workspace=<slug>`) tells the operator to disambiguate. No silent “picks the first one” behaviour.
`reset-password`	Mints a new bcrypt hash for `--email=…`. Interactive password prompt by default; `--password=…` for scripted use (CI bootstrap); `--password-stdin` reads the password from stdin so it never lands in shell history or `ps`. ALSO revokes every active session for that user in the same transaction (with `revoked_reason='password_change'`) and clears any lockout (`failed_login_count=0`, `locked_until=NULL`) so any leaked cookie can’t outlive the recovery — no separate restart needed.
`invalidate-sessions`	Revokes every active session for `--email=…` WITHOUT changing the password. The user can log in normally on the next attempt; only their cached cookies stop working. Audited as `revoked_reason='admin_invalidate'` so the journal distinguishes this from password-change revokes.
`list-users`	Reads the `users` table and renders it via `text/tabwriter`. Email, name, created-at, lockout status (`-` / `LOCKED until <ts>` / `expired <ts>`), failed-login count, workspace roles. Footer summarizes the active-lockout count with a hint to `reset-password` when any exist. Accepts `--locked-only` to filter to just the currently-locked accounts. Usually run before `reset-password` to verify the email row exists with the expected casing.
`promote`	Rewrites a single `workspace_members` row to the requested role. Errors if the user isn’t a member of the resolved workspace. *Unlike the HTTP role endpoints, it does not* guard against demoting the last `OWNER`** of a workspace — a direct write can leave a workspace ownerless, so double-check with `list-users` first.

Usage

Every admin subcommand expects access to the same SQLite file the server uses. Stop the server first — concurrent writes from two processes against the same DB are the failure mode this guard exists to prevent.

1. Stop the server (if running)

# Stop the process you started with `crewship start` (Ctrl-C in its terminal),
# or if you run it as a systemd unit:
sudo systemctl stop crewshipd

The admin CLI opens the database with a 30-second busy_timeout, so a write that races a running server will wait rather than fail outright. Stop the server anyway — a half-applied change racing the server’s own connection is exactly the failure mode to avoid.

2. Verify the user exists

crewship admin list-users

Outputs a tab-aligned table:

EMAIL                NAME           CREATED              LOCKED                       FAILS  ROLES
admin@example.com    Pavel Srba     2025-11-14 09:21     -                            -      OWNER@acme
ops@example.com      Ops Team       2026-02-01 12:00     -                            -      ADMIN@acme
intruder@e.com       -              2026-05-22 03:14     LOCKED until 2026-05-24 12:31  5    MANAGER@acme

1 account(s) currently locked out. Unlock with: crewship admin reset-password --email <email>

The LOCKED column shows one of - (no lockout), LOCKED until <ts> (currently locked — the account can’t log in), or expired <ts> (had a lockout that has cooled down). The FAILS column is the per-account failed_login_count the brute-force protection increments on each bad credential attempt. The footer appears only when at least one account is actively locked. To filter to just the currently-locked accounts:

crewship admin list-users --locked-only

The admin CLI lowercases the --email argument before querying, so it can only target rows whose stored email is already lowercase. Since web signup stores email verbatim, run list-users first to confirm the row exists in lowercase form; if the row you want isn’t matched, reset-password fails loudly rather than silently creating a new one.

3. Reset a password

Interactive (preferred — the password is not logged anywhere):

crewship admin reset-password --email=admin@example.com
# New password: ********
# Confirm password: ********
# ✓ Password reset for Pavel Srba (admin@example.com).
#   2 active session(s) revoked.
#   Lockout (if any) cleared.

Scripted (for CI / Docker provisioning):

crewship admin reset-password \
  --email=admin@example.com \
  --password="$BOOTSTRAP_PASSWORD"

Never embed the password as a literal in a shell history — pass it via env var or stdin redirection so it lands neither in ~/.bash_history nor in ps. The leak-free pattern is --password-stdin:

op read op://Dev/crewship/admin | crewship admin reset-password \
  --email=admin@example.com \
  --password-stdin

--password-stdin reads stdin verbatim (preserving embedded spaces and UTF-8; trims exactly one trailing LF/CRLF). The flag is mutually exclusive with --password — passing both is a configuration error.

4. Invalidate all sessions WITHOUT changing the password

crewship admin invalidate-sessions --email=alice@example.com
# ✓ Sessions invalidated for Alice Example (alice@example.com).
#   3 active session(s) revoked.

Use when the password is believed safe but a session token / cookie is suspected leaked — stolen laptop you’ve recovered access to, a cookie pasted into a Slack DM, a screenshot of dev tools, etc. The user can sign in normally on the next attempt; only the cached cookies on the lost devices stop working. The audit row carries revoked_reason='admin_invalidate', distinguishing this from password_change (issued by reset-password) and user_logout (the “log out from all devices” button in the UI). reset-password already revokes sessions as a side effect; reach for invalidate-sessions only when you want JUST the force-logout. The separate verb keeps the audit story clean — a combined --invalidate-sessions-only flag on reset-password would obscure the operator’s intent.

5. Promote (or demote) a workspace role

# Single-workspace user — slug is inferred:
crewship admin promote --email=admin@example.com --role=OWNER

# Multi-workspace user — slug is required:
crewship admin promote \
  --email=admin@example.com \
  --role=ADMIN \
  --workspace=acme-research

The role must be one of OWNER, ADMIN, MANAGER, MEMBER, or VIEWER. Note that promote writes the row directly and does not stop you from demoting the last OWNER of a workspace — verify with list-users first if you’re changing an owner.

6. Restart the server

crewship start
# or
sudo systemctl start crewshipd

The new password is now active. The user logs in normally. Because the write bypassed the HTTP layer, it leaves no entry on the in-app audit timeline — note the recovery in your own operational log if you need it traced.

Examples

Locked-out solo admin, no mailer configured

You’re the sole OWNER of a self-hosted Crewship instance. The mailer was never set up (RESEND_API_KEY is unset), /forgot returns 200 but no email goes out, and you’ve forgotten your password. SSH to the host:

ssh prod-server
sudo systemctl stop crewshipd
sudo -u crewship crewship admin list-users
# admin@example.com   OWNER   2025-09-01 14:22   2026-04-30 09:15
sudo -u crewship crewship admin reset-password --email=admin@example.com
# New password: ********
sudo systemctl start crewshipd

The whole recovery is four commands. The sudo -u crewship matters: the data directory is owned by the service account, so running the admin CLI as root would create root-owned WAL files that confuse the next server start.

CI bootstrap of a freshly migrated database

A Dockerfile that bakes a baseline workspace for a demo deployment:

FROM crewship-ai/crewship:latest

# Migrations apply automatically the first time the server boots
# (`crewship start` runs them before serving), so there's no separate
# migrate step to bake into the image.

# Seed the OWNER account. The password is mounted as a BuildKit secret so it
# never lands in image layers or metadata; the email is a plain ARG because
# email addresses aren't sensitive.
ARG BOOTSTRAP_EMAIL
RUN --mount=type=secret,id=bootstrap_password \
    crewship admin reset-password \
      --email="$BOOTSTRAP_EMAIL" \
      --password="$(cat /run/secrets/bootstrap_password)" \
  && crewship admin promote \
      --email="$BOOTSTRAP_EMAIL" \
      --role=OWNER

CMD ["crewship", "start"]

Build the image with docker buildx build --secret id=bootstrap_password,src=./bootstrap.pw … — the secret file is mounted only for the duration of that one RUN step and never becomes part of any image layer. Never use plain ARG BOOTSTRAP_PASSWORD: build args land in image history and are recoverable via docker history <image> for anyone who pulls the resulting image. The HTTP API isn’t running during RUN steps — crewship admin is the only path that can produce a logged-in-able user before the server boots for the first time.

Restoring `OWNER` after a botched demotion

A MANAGER accidentally clicked “Demote to ADMIN” on the only OWNER of the marketing workspace. The web UI now refuses every elevation request from that user (no OWNER left to authorise it). Recovery on the host:

sudo systemctl stop crewshipd
crewship admin promote \
  --email=lead@example.com \
  --role=OWNER \
  --workspace=marketing
# ✓ Promoted lead@example.com to OWNER in workspace "Marketing" (marketing).
sudo systemctl start crewshipd

Because the change is a direct DB write it does not appear on the in-app audit timeline, so a postmortem reader won’t see how the workspace got unstuck unless the operator records the rescue elsewhere — note it in your incident log.

API reference

The admin CLI is deliberately not exposed as an HTTP API — that’s the whole point of the surface. Every other Crewship feature has a /api-reference/<thing> page; this one does not. Routing recovery through the same server you’re recovering would be circular, and exposing these writes over HTTP would create a parallel auth surface to harden when the existing one already covers every healthy-system case. The full source of truth is one file: cmd/crewship/cmd_admin.go (~814 lines). It’s small enough to read top-to-bottom; the test file cmd_admin_test.go covers the same surface. The SQL surface area each subcommand touches:

Subcommand	Tables written	Constraints enforced
`reset-password`	`users.hashed_password`, `users.failed_login_count`, `users.locked_until`, `users.last_failed_login_at`, `users.updated_at`	Email must exist (no implicit `INSERT`). Resetting also unlocks the account and clears the failed-login counter.
`list-users`	(read-only)	None — reads `users` joined to `workspace_members`/`workspaces` for email, name, created-at, `locked_until`, `failed_login_count`, and per-workspace roles.
`promote`	`workspace_members.role`	Role must be one of `OWNER`/`ADMIN`/`MANAGER`/`MEMBER`/`VIEWER`; if `--workspace` omitted, user must belong to exactly one workspace. Errors if the user isn’t a member of the target workspace.
`invalidate-sessions`	`user_sessions.revoked_at`, `user_sessions.revoked_reason`	Email must exist. Revokes only currently-active rows (`revoked_at IS NULL AND expires_at > now`), stamping `revoked_reason='admin_invalidate'`. Leaves the password untouched.
`sessions list`	(read-only)	Email must exist. Dumps `user_sessions` for the user (all rows by default; `--active-only` filters to non-revoked, unexpired; `--limit` caps, default 50).

None of these writes append to journal_entries — they bypass the HTTP audit middleware entirely. If you need the change traced, record it out of band. For the user/workspace data model these commands operate on, see the Admin API reference — the underlying schemas are the same; the admin CLI just bypasses the HTTP layer that normally fronts them.

Common pitfalls

Don’t run as root against a service-owned data directory. If crewshipd runs as a crewship system user, the data directory is owned by that account. Running crewship admin as root creates root-owned WAL / journal files; on next server start, crewshipd can’t write them and the server bails with a permissions error. Always sudo -u crewship crewship admin ….
Stop the server first, every time. Two processes writing the same SQLite file is the failure mode to avoid. The admin CLI does not lock the server out — it opens the DB with a 30s busy_timeout, so a racing write just waits — but a half-applied change interleaved with the server’s own writes is still a partially-applied-state risk. Stop the server, then run the command.
Take a backup before any write. There is no undo for reset-password or promote. A crewship backup create (or just a copy of crewship.db) before the recovery makes a botched call a one-command rollback instead of a multi-hour incident.
The admin CLI lowercases --email. Every admin subcommand runs strings.ToLower on the --email argument before querying. Web signup stores emails as typed, so a user who registered as Admin@example.com cannot be targeted by these commands (the lowercased admin@example.com won’t match the stored row). Run list-users first: if the row you need shows mixed case, fix it through the app, not the CLI.
reset-password DOES invalidate active sessions. Every active session for the user is revoked in the same transaction as the password change (revoked_reason='password_change'), so a leaked cookie can’t outlive the recovery. No server restart needed — the next request on the old cookie returns 401. If you want force-logout WITHOUT changing the password (suspected token leak but the password is believed safe), use crewship admin invalidate-sessions instead.
Don’t put the password in shell history. --password='…' lands in ~/.bash_history and is visible in ps to anyone with shell access during the window the command runs. Prefer the interactive prompt; for scripted use, pass via --password="$VAR" where VAR is sourced from an env file or BuildKit secret mount.
CREWSHIP_DATA_DIR overrides ~/.crewship. On a host where the service was started with a custom data dir (common on dev VMs), running crewship admin with default env points at the wrong empty database, silently fails to find the user, and prints a misleading “no such email” error. Export the same CREWSHIP_DATA_DIR the service uses (there is no --data-dir flag). If the service was configured with an explicit DATABASE_URL instead, set that — it takes precedence over CREWSHIP_DATA_DIR in the admin CLI’s resolution.
Migration version conflicts can hide your write. If the data directory predates the migration that added the column you’re updating (e.g. password_updated_at), the write succeeds but the new column stays at its default. Migrations apply automatically on crewship start, so start the server once against an older database (letting it migrate) before running crewship admin against it.

Authentication — the in-band recovery flow (email-based password reset) for users without shell access.
Backup — what to do before running admin commands against a production database.
Installation — where CREWSHIP_DATA_DIR is configured and the SQLite file lives.

Get Started

Guides

Security

Configuration

Manifest Reference

Admin CLI

Admin CLI

Overview

When to use it

Key concepts

Usage

1. Stop the server (if running)

2. Verify the user exists

3. Reset a password

4. Invalidate all sessions WITHOUT changing the password

5. Promote (or demote) a workspace role

6. Restart the server

Examples

Locked-out solo admin, no mailer configured

CI bootstrap of a freshly migrated database

Restoring `OWNER` after a botched demotion

API reference

Common pitfalls

​Admin CLI

​Overview

​When to use it

​Key concepts

​Usage

​1. Stop the server (if running)

​2. Verify the user exists

​3. Reset a password

​4. Invalidate all sessions WITHOUT changing the password

​5. Promote (or demote) a workspace role

​6. Restart the server

​Examples

​Locked-out solo admin, no mailer configured

​CI bootstrap of a freshly migrated database

​Restoring OWNER after a botched demotion

​API reference

​Common pitfalls

​Related

Admin CLI

Overview

When to use it

Key concepts

Usage

1. Stop the server (if running)

2. Verify the user exists

3. Reset a password

4. Invalidate all sessions WITHOUT changing the password

5. Promote (or demote) a workspace role

6. Restart the server

Examples

Locked-out solo admin, no mailer configured

CI bootstrap of a freshly migrated database

Restoring `OWNER` after a botched demotion

API reference

Common pitfalls

Related