> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vetta org

> Organizations, the active-org profile setting, and members.

An organization owns every other resource — agents, sessions, credits, keys. `vetta login` writes the active org onto your profile from `GET /v1/me`; `--org org_…` overrides it for one command.

## Commands

| Command                        | Description                                                  |
| ------------------------------ | ------------------------------------------------------------ |
| `vetta org list`               | Every organization this credential reaches. Needs no org id. |
| `vetta org create`             | Create an organization. Returns a working `admin` key, once. |
| `vetta org use <org-id>`       | Write an org id onto the active profile.                     |
| `vetta org show`               | Show the active organization.                                |
| `vetta org update`             | Rename the active organization.                              |
| `vetta org members`            | List members.                                                |
| `vetta org invite`             | Invite a member by email with a role.                        |
| `vetta org set-role <user-id>` | Change a member's role.                                      |
| `vetta org remove <user-id>`   | Remove a member.                                             |

<Note>
  Members are addressed by **`usr_` id**, not by email — `set-role` and `remove` take the id from `vetta org members`. Only `invite` takes an email, because the user may not exist yet.
</Note>

## list

```bash theme={"system"}
vetta org list
```

```json theme={"system"}
{
  "data": [
    {
      "id": "org_gj9xg0gx6bpvdaysqvz68vr7b5",
      "object": "organization",
      "name": "acme-staging",
      "balance_micro_usd": 79416537,
      "created_at": "2026-08-21T12:05:48.146Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

`list` and `create` are the two commands that need no org id — everything else reads it from the profile. Without one they fail fast:

```
error: no organization on this profile; run `vetta login` or pass --org org_…
```

## create

```bash theme={"system"}
vetta org create --name "Acme" --use
```

| Flag     | Description                                        |
| -------- | -------------------------------------------------- |
| `--name` | Organization name (required).                      |
| `--use`  | Also write the new org id onto the active profile. |

<Warning>
  The reply carries a working `admin` API key for the new organization, and its secret appears **once**. Store it before the terminal scrolls; there is no way to read it back.
</Warning>

## use / show / update

```bash theme={"system"}
vetta org use org_gj9xg0gx6bpvdaysqvz68vr7b5
vetta org show
vetta org update --name "Acme Inc"
```

`show` returns the org record including its live credit balance:

```json theme={"system"}
{
  "id": "org_gj9xg0gx6bpvdaysqvz68vr7b5",
  "object": "organization",
  "name": "acme-staging",
  "balance_micro_usd": 79416537,
  "created_at": "2026-08-21T12:05:48.146Z"
}
```

## members

```bash theme={"system"}
vetta org members --limit 2
```

```json theme={"system"}
{
  "data": [
    {
      "id": "usr_hskm9b2nvg2egn9v9anddadr77",
      "object": "member",
      "email": "alice@example.com",
      "role": "member",
      "invited_by": "key_66nnedy98yfx3ygzssfv99p7tf",
      "created_at": "2026-08-22T16:24:07.077Z"
    }
  ],
  "has_more": true,
  "next_cursor": "usr_vptzsa5p9ayh3ykdsk5g3nmmz9"
}
```

| Flag      | Description |
| --------- | ----------- |
| `--limit` | Page size.  |

## invite, set-role, remove

```bash theme={"system"}
vetta org invite --email alice@acme.com --role admin
vetta org set-role usr_hskm9b2nvg2egn9v9anddadr77 --role member
vetta org remove usr_hskm9b2nvg2egn9v9anddadr77
```

| Flag      | Description                                                          |
| --------- | -------------------------------------------------------------------- |
| `--email` | Invitee's email (`invite` only, required).                           |
| `--role`  | `owner` \| `admin` \| `member`. Required by `invite` and `set-role`. |

`--role` is validated **client-side** against the shared role enum, so a typo fails before anything is sent rather than coming back as a 400.