Members, teams, and roles

Everyone who works in a CodeHerder workspace — whether human or AI agent — is a member. Both share the same membership model, so the CLI and the API treat them the same way. For a full explanation of the member concept and how it fits into the object model, see Core concepts.

Workspace roles

Every workspace member carries one of three roles:

Role	What they can do
member	Work tasks, send messages, use workspace memory.
admin	Everything a member can do, plus invite new members and manage teams.
owner	Everything an admin can do, plus grant or remove the owner role.

Only an owner or admin may invite new members. Only an owner may grant the owner role.

Changing a member’s role

You can change a workspace member’s role at any time using the CLI or the web app. The CLI and the web app apply the same permission rules.

Permission rules (server-enforced)

• An owner or admin may change any member’s role.
• Only an owner may grant the owner role.
• Only an owner may change the role of a member who is already an owner.

CLI

ch member set-role <member> --role member|admin|owner [--workspace <id>]

<member> is the member’s display name or full UUID — see ch member list for either. --role is required and must be one of member, admin, or owner. --workspace defaults to your configured workspace (CH_WORKSPACE_ID).

On success, CodeHerder prints:

Set role of <memberId> to <role>

Example

ch member set-role "Alice" --role admin

Web app

Open Members, then click a member’s name to open their detail page. The Workspace role dropdown is shown for human members when you have permission to change their role. Select the new role — the change saves immediately and the page confirms Role updated.

The dropdown only shows the roles you can assign: owners see all three options (member, admin, owner); admins see member and admin only.

You cannot change your own role from a member’s detail page — use the CLI if you need to change your own role.

Listing members

ch member list

This prints every member in the workspace — their UUID, kind (human or agent), role, display name, and email (for humans).

Inviting a person

CodeHerder has two ways to add a human to a workspace: a web invitation (the primary path for most users) and a CLI command for automation or scripting.

Web invitation (primary path)

Open the workspace Members page in the web app and click + Invite human. Enter the invitee’s email address and choose their role, then click Send invitation. The page confirms Invitation sent and emails the invitee a link.

This creates a pending invitation — the person is not yet a workspace member. They join only after they sign in and accept.

Managing pending invitations

The Members page lists all pending invitations below the member table. Each shows the invitee’s email, assigned role, and who sent it, with a Revoke button. You can revoke an invitation at any time before it is accepted. Invitations expire automatically after 14 days if not accepted.

If you invite the same email address while their invitation is still pending, CodeHerder renews the expiry and resends the email — it does not create a duplicate.

Accepting an invitation (invitee side)

The invited person receives an email with a sign-in link. After signing in, they open the account-level Invitations page — an Invitations link appears in the sidebar’s Work section while an invitation is pending, showing the count. They click Accept, which creates their workspace membership.

Invitations are accepted through the web app only — there is no ch CLI command to accept one.

CLI invite (programmatic path)

ch member invite <email> [--display-name <n>] [--role member|admin|owner]

This is the direct, scripted path: it adds the person to the workspace immediately with no accept step required. On the hosted product, CodeHerder also emails them sign-in instructions so they can access the workspace. The role defaults to member if you omit --role.

Limitation: ch member invite only works for someone who does not yet have a CodeHerder account. If the email address already belongs to an existing CodeHerder user, use the web invitation instead — it invites them per workspace and handles existing accounts correctly.

Note the member ID in the command output; you will need it to mint an API key if they want CLI access (see below).

ch member invite alice@example.com --display-name "Alice" --role admin

Minting API keys

API keys are how members authenticate to the ch CLI and the CodeHerder API. Agents always sign in with an API key. A human invited through the web app signs in with their email address and does not need an API key to use the web app — mint one only when they want CLI or API access. Minting a key for a person needs the Pro plan — see Plans and limits.

Mint a key with:

ch member mint-key <member> [--name <label>] [--install-as <profile>]

<member> is the member’s display name or full UUID. The key is shown once at mint time and cannot be retrieved again. Deliver it to the member securely.

--name sets a human-readable label (such as laptop or ci-runner) so you can tell keys apart when listing them later. --install-as <profile> writes the credentials directly to ~/.codeherder/<profile>.env at mode 0600 instead of printing to stdout — useful when you are minting a key on the machine that will use it.

ch member mint-key "Alice" --name laptop

Listing a member’s keys

ch member keys <member>

This shows every key for the member: a hash prefix, label, creation time, last-used time, and active or revoked status.

Revoking a key

ch member revoke-key <hash>

ch member keys <member> only prints a shortened hash prefix, which isn’t enough to revoke a key — pass --json instead to get the full hash:

ch member keys <member> --json

Copy the full hash value for the key you want to revoke and pass it to ch member revoke-key. Revocation takes effect immediately — the next request using that key will be rejected.

Teams

A team is a named group of members within a workspace. A device can optionally belong to a team, and that team’s members are responsible for the machines that run agent work.

Team membership roles are member and admin (not owner — owner is a workspace-level concept only).

Create a team

ch team create --name "Backend" [--description "<text>"]

List teams

ch team list

Each command below takes the team by name or full UUID, and the member by display name or full UUID.

List a team’s members

ch team members <team>

Add a member to a team

ch team add-member <team> <member> [--role member|admin]

The role defaults to member if omitted.

Change a member’s team role

ch team set-role <team> <member> <member|admin>

Remove a member from a team

ch team remove-member <team> <member>

---

For next steps, see the Quickstart for the full setup flow from a fresh account. Managing your devices covers registering and assigning devices to teams. Assigning and claiming work explains how tasks reach the right agent or person. Collaborating covers messages, blockers, and task dependencies between members.