Teams, projects, and roles

The getting-started and tour guides run everything locally against spool dev. This page is the other half: using a shared Hyperspool server with your team. It covers signing in, how work is organised into orgs and projects, and who can do what.

The shape

Two nouns hold everything:

An org is your team’s tenant. It owns projects, members, an agent fleet, and its own encrypted secrets. Billing and isolation are per org: one org can never see another’s runs, secrets, or members.
A project is a workspace inside an org, usually one per service or repo. Runs, secrets, schedules, the event bus, and the webhook connection all live at the project level. A run id spells out both: myorg:api:run-3xKq….

You belong to one or more orgs, with a role in each (below), plus optional grants on individual projects.

Signing in

Get a personal access token from the web UI (sign in, then Settings → Tokens), then point the CLI at the server:

spool login https://spool.example.com --token cspat_…

That verifies the token, resolves your org and project from your memberships, and writes config.toml. From then on every command targets that server; override per command with --org / --project or $HYPERSPOOL_ORG / $HYPERSPOOL_PROJECT. spool where shows the current target, spool config show the resolved settings.

Projects

List the projects you can see, and create one (org owner or admin):

spool project ls
spool project create api --name "API service"
spool project create web --name "Web app"

Submit work to a specific project with --project; the run id it prints is fully qualified, so you can paste it straight back into any run command:

run=$(spool submit ./pipeline.yaml --project api)
spool status "$run"
spool logs "$run" --follow

Delete a project (and its scoped state) with spool project rm <slug>; it refuses while runs are executing.

Members and roles

Every membership carries one of four roles. They’re ranked, so a higher role includes everything below it:

Role	Can
`viewer`	read: list and watch runs, read logs, list secret names
`member`	the above, plus run workflows (submit, cancel, signal)
`admin`	the above, plus manage members, secrets (set and delete; no role reads a value back), schedules, webhooks, and caps
`owner`	the above, plus delete the project and change ownership; an org owner also mints agent tokens for the org and its projects

Roles apply at two levels, and your effective role on a project is the higher of the two:

An org-wide role (spool org members) applies to every project in the org.
A project grant (spool project members) admits someone to just that one project, with no org-wide access. Use it to give a contractor member on web without letting them see api. A grant stops at admin; owner is an org-level role only.

Add people by email. Both commands create the Hyperspool user if the email is new, and on a server wired to its identity provider they also create the login and send the invite mail; the command prints which of that happened, so there is no separate invite step:

# Org-wide: a teammate who works across all projects
spool org members add dana@example.com --role member

# Project-scoped: a contractor on one project, read-only on nothing else
spool project members add sam@example.com --role member --project web
spool project members add sam@example.com --role viewer --project api

spool org members ls and spool project members ls list current members (admin-gated). The org’s last owner can’t be demoted or removed, so an org can’t be left ownerless.

When a permission check fails, the error says why: you don't have access to \myorg/api`, or this needs the `member` role on `myorg/web`; you have `viewer``. Ask an org or project admin to grant you with the commands above.

What’s project-scoped

These all belong to a project and follow the same role rules:

Secrets - encrypted config, injected into jobs.
Schedules - recurring runs.
Events and handlers - the project bus.
The webhook connection - one endpoint per project, serving as many repos as you point at it.

Agents are matched to work by capability, and their token sets how wide they reach: an unscoped token is a shared fleet that claims any org’s work; a token scoped to an org claims that org’s projects; a token scoped to org/project claims just that one. See deploying agents.