Skip to content

User Management#

Concourse ships with a users CLI for creating, editing, and removing user accounts, assigning roles, granting environment permissions, and inspecting live sessions. Every subcommand is invoked through the concourse wrapper on the server host:

1
concourse users <subcommand> [options] [arguments]

All subcommands require an administrator credential. If you do not pass -u and --password, you will be prompted interactively. Any argument that is not supplied on the command line will also be prompted for.

Roles#

Every account has exactly one role:

Role Capabilities
ADMIN Full administrative access. May run management CLIs, including users.
USER Standard data access, scoped by environment grants. May not invoke management functions.

Role is assigned at creation time with --set-role (or interactively) and can be changed later with users edit.

users create#

Create a new account.

1
2
3
concourse users create <username> \
    --set-password <password> \
    --set-role <ADMIN|USER>

If any of <username>, --set-password, or --set-role is omitted, the CLI prompts for it. The password is confirmed with a re-entry prompt when entered interactively.

users edit#

Change a user’s password and/or role.

1
2
concourse users edit <username> --set-role <ADMIN|USER>
concourse users edit <username> --set-password <password>

Editing a user’s password invalidates that user’s current access token. When both --set-password and --set-role are provided, the role change is applied first so that password invalidation does not disrupt the atomicity of the edit.

users password#

Change a user’s password without touching their role. Equivalent to users edit --set-password, but the dedicated subcommand is handy for password rotation scripts.

1
2
concourse users password <username> \
    --set-password <password>

Interactive mode prompts for the new password twice to confirm.

users delete#

Permanently remove a user account.

1
concourse users delete <username>

Deleted accounts cannot be recovered. If the deleted user is currently connected, their active tokens are invalidated immediately.

users grant#

Grant an environment-scoped permission to a user.

1
2
3
concourse users grant <username> \
    --permission <READ|WRITE|ADMIN> \
    --environment <env>

If --environment is omitted, the server’s default environment is used. The permission argument is required.

Permissions are additive: repeated grant calls accumulate, rather than replacing prior grants.

users revoke#

Revoke all permissions a user holds in a given environment.

1
concourse users revoke <username> --environment <env>

Revocation only affects the named environment. Permissions in other environments are unchanged.

users suspend and users enable#

suspend disables an account without deleting it. The user’s active tokens are invalidated and new sign-in attempts are rejected.

1
concourse users suspend <username>

enable reverses a previous suspension:

1
concourse users enable <username>

A user cannot suspend themselves. Attempting to do so from a session owned by the target user will fail.

users sessions#

List currently active client sessions on the server:

1
concourse users sessions

The output shows each authenticated user along with connection metadata. Use this as the first step when diagnosing “who is holding this lock?” or “why are so many connections open?” incidents.

Scripting#

Every subcommand can run non-interactively when all arguments are passed as flags. This makes the CLI friendly to provisioning systems such as Ansible or shell scripts:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
#!/usr/bin/env bash
set -euo pipefail

concourse users create alice \
    --set-password "$ALICE_PASSWORD" \
    --set-role USER

concourse users grant alice \
    --permission WRITE \
    --environment production

concourse users grant alice \
    --permission READ \
    --environment staging

For broader account and access-token behavior, see Authentication.