Skip to main content

Role Commands

Role commands let you discover and inspect privileged roles available in your GrantFlow tenant. These commands help you understand what access you can request before submitting an activation request.

grantflow roles list​

Display all privileged roles you're eligible to activate. This command shows roles configured by your administrators along with key metadata like approval requirements and maximum duration.

Usage​

List Roles
grantflow roles list [--output table|json|yaml]

Parameters​

  • --output - Output format (default: table)

Example​

List Roles Example
$ grantflow roles list
ID                      NAME                    DESCRIPTION              MAX_DURATION  APPROVERPOLICYID
role-prod-dba           Production DBA          Prod database admin      480           policy-123
role-azure-contributor  Azure Contributor       Azure subscription       240           policy-456
role-ad-admin           AD Admin                Active Directory admin   120           policy-789

Understanding the Output​

Each row represents a role you can request activation for. The columns provide important details:

The role ID uniquely identifies the role and is what you'll use when requesting activation. The name and description help you understand what privileges the role grants.

The max duration column shows the longest activation period allowed, measured in minutes. When you request activation, you can ask for any duration up to this limit. Keep in mind that some roles may have approval policies requiring manager review before granting access.

JSON Output​

When you need to parse role data programmatically, use JSON format:

List Roles - JSON
$ grantflow roles list --output json
[
{
  "id": "role-prod-dba",
  "name": "Production DBA",
  "description": "Prod database admin",
  "maxDuration": 480,
  "approverPolicyId": "policy-123"
},
{
  "id": "role-azure-contributor",
  "name": "Azure Contributor",
  "description": "Azure subscription",
  "maxDuration": 240,
  "approverPolicyId": "policy-456"
}
]

This format works well with tools like jq for filtering and transformation:

Filter Roles
# Find roles with max duration over 4 hours
grantflow roles list --output json | jq '.[] | select(.maxDuration > 240)'

# Extract just the role IDs
grantflow roles list --output json | jq -r '.[].id'

When No Roles Are Available​

If you see an empty result, you may not have any role assignments yet. Contact your GrantFlow administrator to request eligible role assignments. Administrators can assign roles through the web portal or using the grantflow admin roles commands.

grantflow roles get​

Retrieve detailed information about a specific role, including its configuration, requirements, and associated policies.

Usage​

Get Role Details
grantflow roles get <role-id> [--output table|json|yaml]

Parameters​

  • <role-id> (required) - The ID of the role to retrieve
  • --output - Output format (default: table)

Example​

Get Role Example
$ grantflow roles get role-prod-dba
ID:               role-prod-dba
NAME:             Production DBA
DESCRIPTION:      Prod database admin
MAXDURATION:      480
APPROVERPOLICYID: policy-123

Use Cases​

This command helps you understand the specifics of a role before requesting activation. You might use it to verify the maximum duration allowed, check whether approval is required, or confirm you're requesting the correct role for your needs.

It's also useful in scripts when you need to make decisions based on role properties:

Use Role in Script
# Get max duration and use it in an activation request
MAX_DURATION=$(grantflow roles get role-prod-dba --output json | jq -r '.maxDuration')
grantflow activations request role-prod-dba --duration "$MAX_DURATION"

Error Handling​

If you specify an invalid role ID, you'll receive a clear error message:

Error Example
$ grantflow roles get invalid-role
Error: role not found: invalid-role

This typically means either the role doesn't exist or you don't have permission to view it. Double-check the role ID using grantflow roles list.

Finding Roles​

If you're looking for a specific type of access but don't know the exact role ID, combine the list command with filtering:

Search for Roles
# List all roles and search for "database" in the output
grantflow roles list | grep -i database

# Use jq to filter JSON output
grantflow roles list --output json | jq '.[] | select(.name | contains("DBA"))'

You can also use the GrantFlow web interface to browse roles with a richer search and filter experience.

Next Steps​

Once you've identified a role you need, proceed to the Activation Commands documentation to learn how to request just-in-time access.

For administrators creating or managing roles, see the Admin Commands reference.

Related Topics​

Last updated on