Getting started

Register the first admin

The first user to call /v1/auth/register against a fresh server becomes the org admin. Everyone else joins via invite.

bash

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "you@example.com"

foostash register \
  --server http://localhost:8400 \
  --email you@example.com \
  --org "Acme"
# registered org=Acme email=you@example.com role=admin

1. The CLI signs the request with your SSH private key.
2. The server creates the org, your user (role admin), and stores your public key.
3. ~/.foostash/config.yaml now carries the server URL and key fingerprint — future commands do not need --server.

Invite teammates

bash

# admin
foostash admin invite --email alice@acme.com --role developer
# invite created (expires 2026-04-21T12:00:00Z)
#
# Share this with alice@acme.com:
#   foostash join <token>

bash

# invitee — must have ~/.ssh/id_ed25519 present
foostash join <token> --server http://localhost:8400
# joined org=Acme email=alice@acme.com role=developer

Roles

admin — create projects and envs, invite users, revoke users, write the shared vault, read the audit log.
developer — read project/env metadata, manage secrets on their own machine, read the shared vault.