> ## 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 [org-id]` | Show the active organization, or the one named. |
| `vetta org update` | Rename the active organization, or set its timezone or logo. |
| `vetta org members [org-id]` | List members of the active organization, or of the one named. |
| `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.

## 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 (or `--org`), and with none there asks the credential itself (`GET /v1/me`), so a key in `VETTA_API_KEY` is enough. `show` and `members` also take the org id on the line, which wins over `--org` and the profile. A credential that reaches no organization fails fast:

```
error: no organization on this profile or credential; 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.

## use / show / update

```bash theme={"system"}
vetta org use org_gj9xg0gx6bpvdaysqvz68vr7b5
vetta org show
vetta org update --name "Acme Inc"
vetta org update --timezone America/Los_Angeles
vetta org update --logo-file ./logo.svg
```

`update` takes `--name`, `--timezone` (an IANA name), `--logo-file` (a path to an SVG file), or any of
them together. The timezone is the company's: a routine created without one runs in it, and the
studio says when a post goes out in it. The logo shows in the studio's top-left corner and in its
apps; the API [checks it](https://vetta.sh/docs/api/organizations.md#the-logo) and says what to change when it refuses.

`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,
  "timezone": "America/New_York",
  "logo_svg": null,
  "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. |
| `--after` | Pagination cursor: the `next_cursor` of the previous page. |

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.