Organizations

An organization owns apps on behalf of a team, so the apps outlive any one person's account and members get access through roles rather than per-app collaborator invites.

Every dpctl command runs against exactly one context: your personal account, or one organization. By default that is your personal account, which is why an organization's apps do not show up in dpctl app ls until you switch.

Organizations are created and managed in the dashboard. The CLI switches between them and runs commands against them; it does not create them or manage membership.

Listing your organizations

dpctl org list

┌───┬──────┬──────────┬───────┐
│   │ Slug │ Name     │ Role  │
├───┼──────┼──────────┼───────┤
│ * │ acme │ Acme Inc │ admin │
└───┴──────┴──────────┴───────┘

The * marks the organization your commands currently run against. dpctl org ls is the same command.

Switching context

dpctl org use acme

Every later command runs against that organization until you change it. The organization can be named by slug, by name, or by id:

dpctl org use acme          # slug
dpctl org use "Acme Inc"    # name
dpctl org use <id>          # id

Slugs are unique, but names are not: two organizations both called "Acme" get the slugs acme and acme-2. If a name matches more than one, dpctl refuses rather than guessing, and asks you for the slug or the id.

To go back to your personal account:

dpctl org clear

Running a single command against an organization

--org works on every command and applies to that one invocation only, leaving your saved context alone:

dpctl app ls --org acme
dpctl release-react MyApp-iOS ios --org acme

In CI

dpctl org use writes to the session file created by dpctl login, so it is not available when you authenticate with an access key. Set DEPLOYPULSE_ORG_ID to the organization's id instead:

export DEPLOYPULSE_ACCESS_KEY=<key>
export DEPLOYPULSE_ORG_ID=<organization id>

dpctl release-react MyApp-iOS ios -d Production

Run dpctl org list --format json while logged in to find the id.

Which context wins

When more than one is set, the most specific wins:

Order	Source	Scope
1	`--org <slug\|name\|id>`	The single command it is passed to
2	`DEPLOYPULSE_ORG_ID`	Every command in that shell
3	`dpctl org use`	Every command on that machine, until changed

DEPLOYPULSE_ORG_ID beating the saved context is deliberate, so a CI job can switch organization without rewriting the session file. It is the opposite of DEPLOYPULSE_ACCESS_KEY, which does not override an existing login. If dpctl org use appears to do nothing, check whether DEPLOYPULSE_ORG_ID is set; dpctl warns when it is.

Roles

Your role in an organization decides what the CLI lets you do. Roles are assigned in the dashboard.

Role	Can
`view`	Read apps, deployments and release history
`deploy`	The above, plus release, promote, roll back and patch
`edit`	The above, plus create, rename and remove apps and deployments
`collaborate`	The above, plus manage app collaborators
`admin`	The above, plus manage the organization and its members

A command your role does not allow fails with a permission error from the server, not a client-side check, so the message tells you what was refused.

What's next?

Transfer an app into or out of an organization
Create scoped access keys for CI