Profiles and organizations

Keep several API profiles, switch the default profile, and choose the organization your commands work in.

Profiles

A profile is a name for an API address with its own stored token. Most people need only the default profile, which points at https://api.managerunners.com without any setup. Additional profiles help when you want separate tokens, for example a read-only one for everyday use and one with write scopes for changes. Create them with config set-api:

manage-runners config set-api --profile admin --url https://api.managerunners.com
manage-runners auth login --profile admin --scope runners:write --scope runners:delete

Profile names start with a letter and contain up to 64 letters, numbers, - and _.

The configuration is stored in manage-runners/config.json in your user configuration directory (for example ~/.config on Linux). It contains no secrets; tokens are kept in the credential store.

Organizations

Runners, schedules, metrics and the subscription belong to an organization. Without a selection, commands use your default organization.

manage-runners org list

org list shows each organization’s ID, name and your role (OWNER, EDITOR or VIEWER), and marks your default organization and the selected one.

To work in another organization:

# for one command
manage-runners --org "Platform Team" runner list

# for every command of the profile
manage-runners org use "Platform Team"

# back to the default organization
manage-runners org use --clear

--org and org use accept an organization ID or name. The CLI looks for an exact ID first, then an exact name, then a unique name ignoring case. An unknown value fails with ORGANIZATION_NOT_FOUND, an ambiguous name with ORGANIZATION_AMBIGUOUS, before anything else is requested. --org applies to runner, schedule, subscription and provider commands and overrides the profile’s selection.

Organization IDs are long numbers. In JSON output they are strings; keep them as strings in scripts.

Roles and token scopes

What a command may do is the intersection of the token’s scopes and your role in the organization. Viewers can read runners, schedules, metrics and the subscription. Editors can also change runners and schedules. If your role does not allow an action, the command fails with ORGANIZATION_PERMISSION_DENIED and exit code 4, naming the organization and your role.

Creating and renaming organizations and managing members and invitations are only possible in the dashboard.

Downgrading the CLI

Older CLI versions without organization support reject a configuration that stores an organization. Before installing such a version, run manage-runners org use --clear --profile <name> for every profile listed by config profiles.