CLI Tool (@auris/cli)

@auris/cli v0.1.0

@auris/cli is the official command-line tool for Auris IAM. Use it to manage users, roles, applications, and audit logs from the terminal — or in CI/CD pipelines and automation scripts.

Installation


# Install globally (recommended)
npm install -g @auris/cli
 
# Or run without installing with npx
npx @auris/cli --help

Verify the installation:


auris --version

Authentication

Before using the CLI, authenticate with your Auris tenant. Run:


auris login

This opens your browser and redirects you to the Auris hosted login page. After signing in, the CLI stores your access and refresh tokens in ~/.aurisrc (or the path set by AURIS_CONFIG_PATH).

To authenticate non-interactively (for CI/CD), set the AURIS_CLIENT_SECRET environment variable and the CLI will use M2M client_credentials authentication automatically:


export AURIS_DOMAIN=auth.yourdomain.com
export AURIS_CLIENT_ID=app_xxxxx
export AURIS_CLIENT_SECRET=cs_live_xxxxx
export AURIS_TENANT=my-tenant
 
auris users list

Configuration File (`.aurisrc`)

The CLI reads configuration from a .aurisrc file. The default location is ~/.aurisrc. The file is created automatically by auris init or auris login.


{
  "domain": "auth.yourdomain.com",
  "clientId": "app_xxxxx",
  "tenant": "my-tenant",
  "outputFormat": "table"
}

Configuration options:

Key	Type	Default	Description
`domain`	`string`	—	Auris tenant domain (without `https://`)
`clientId`	`string`	—	Application Client ID
`tenant`	`string`	`'default'`	Tenant identifier sent as `x-tenant` header
`outputFormat`	`'table' \| 'json'`	`'table'`	Default output format

Use --config /path/to/.aurisrc to specify an alternate config file for multi-tenant workflows.

Environment Variables

All configuration options can be set via environment variables. Environment variables take precedence over the config file.

Variable	Description
`AURIS_DOMAIN`	Auris tenant domain
`AURIS_CLIENT_ID`	Application Client ID
`AURIS_CLIENT_SECRET`	Client secret (enables M2M auth — for CI/CD)
`AURIS_TENANT`	Tenant identifier
`AURIS_CONFIG_PATH`	Path to `.aurisrc` config file (default: `~/.aurisrc`)
`AURIS_OUTPUT_FORMAT`	`table` or `json` (default: `table`)

Global Flags

These flags apply to all commands:

Flag	Description
`--json`	Output as JSON (overrides `outputFormat` in config)
`--tenant <id>`	Override the tenant for this command
`--config <path>`	Use a custom config file
`--no-color`	Disable colored output
`--quiet`	Suppress all output except errors
`--verbose`	Show HTTP request/response details
`--help`	Show help for the current command
`--version`	Show CLI version

Commands

`auris init`

Interactively create a .aurisrc config file in the current directory. Prompts for domain, client ID, and tenant.


auris init


? Auris domain: auth.yourdomain.com
? Client ID: app_xxxxx
? Tenant: my-tenant
? Default output format: table

Created .aurisrc in current directory.

Use --global to write to ~/.aurisrc instead of the current directory.


auris init --global

`auris login`

Authenticate with Auris. Opens a browser window for the OAuth2 PKCE flow. Stores the resulting tokens in the config file.


auris login


# Specify a tenant at login time
auris login --tenant my-tenant

After successful login, the CLI prints the authenticated user’s name and email.

`auris whoami`

Display information about the currently authenticated user.


auris whoami


User:   Alice Smith
Email:  [email protected]
ID:     usr_abc123
Roles:  admin, editor
Tenant: my-tenant

`auris test`

Test connectivity to the configured Auris instance. Checks that the domain is reachable, the client ID is valid, and the current token is accepted.


auris test


Connecting to auth.yourdomain.com... OK
Client ID app_xxxxx... valid
Token... valid (expires in 42 minutes)
All checks passed.

`auris applications list`

List all applications in the current tenant.


auris applications list
auris applications list --json


ID              NAME                TYPE    STATUS
app_abc123      My Web App          WEB     active
app_def456      Mobile App          MOBILE  active
app_ghi789      Reporting Service   M2M     active

Flags:

--type <web|mobile|api|m2m> — Filter by application type
--status <active|inactive> — Filter by status

`auris applications create`

Create a new application interactively.


auris applications create


? Application name: My New App
? Application type: WEB
? Callback URL: http://localhost:3000/callback
? Allowed logout URL: http://localhost:3000

Created application app_newxxx.
Client ID: app_newxxx

Pass --non-interactive with flags to create without prompts (useful in scripts):


auris applications create \
  --name "My API" \
  --type M2M \
  --non-interactive

`auris users list`

List users in the current tenant with optional filters and pagination.


auris users list
auris users list --page 2 --limit 25
auris users list --role admin
auris users list --search alice

Flags:

Flag	Description
`--page <n>`	Page number (default: 1)
`--limit <n>`	Users per page (default: 20, max: 100)
`--search <query>`	Search by email, username, or name
`--role <name>`	Filter by role name
`--status <enabled\|disabled>`	Filter by account status
`--json`	Output as JSON array


EMAIL                   NAME          ROLES       STATUS
[email protected]       Alice Smith   admin        enabled
[email protected]         Bob Jones     editor       enabled
[email protected]     Charlie Lee   subscriber   disabled

`auris users get <id-or-email>`

Get detailed information about a single user.


auris users get [email protected]
auris users get usr_abc123


ID:             usr_abc123
Email:          [email protected]
Name:           Alice Smith
Username:       alice
Roles:          admin, editor
Status:         enabled
Email verified: yes
Created:        2024-01-15T10:30:00Z
Last login:     2026-02-14T09:00:00Z

`auris users create`

Create a new user interactively or with flags.


# Interactive
auris users create
 
# Non-interactive
auris users create \
  --email "[email protected]" \
  --first-name "New" \
  --last-name "User" \
  --role "editor" \
  --send-invite

Flags:

Flag	Description
`--email <email>`	User’s email address
`--first-name <name>`	First name
`--last-name <name>`	Last name
`--username <username>`	Username (auto-generated from email if omitted)
`--role <name>`	Assign a role (can be specified multiple times)
`--send-invite`	Send a welcome / invitation email to the new user
`--non-interactive`	Do not prompt — fail if required flags are missing

`auris users update <id-or-email>`

Update an existing user’s profile.


auris users update [email protected] --first-name "Alicia"
auris users update usr_abc123 --role editor --role viewer

Flags:

Flag	Description
`--first-name <name>`	Update first name
`--last-name <name>`	Update last name
`--username <username>`	Update username
`--role <name>`	Replace all roles with these (repeatable)
`--enable`	Re-enable a disabled account
`--disable`	Disable the account

`auris users delete <id-or-email>`

Delete a user. Prompts for confirmation unless --yes is passed.


auris users delete [email protected]
auris users delete [email protected] --yes

`auris roles list`

List all roles in the current tenant.


auris roles list


ID           NAME         DESCRIPTION              USERS
role_abc     admin        Full administrative access    3
role_def     editor       Can edit content              12
role_ghi     viewer       Read-only access              45

`auris roles get <id-or-name>`

Get detailed information about a role including its permissions.


auris roles get admin
auris roles get role_abc123

`auris roles create`

Create a new role.


auris roles create --name "billing-manager" --description "Manages billing and invoices"

`auris permissions list`

List all permission definitions available in the tenant.


auris permissions list
auris permissions list --role admin
auris permissions list --category billing

Flags:

Flag	Description
`--role <name>`	Show only permissions assigned to this role
`--category <name>`	Filter by permission category
`--json`	Output as JSON

`auris logs`

View audit logs with optional filters. Defaults to the last 50 log entries.


# Show recent logs
auris logs
 
# Filter by level
auris logs --level error
 
# Filter by action type
auris logs --action user.login
 
# Filter by time range
auris logs --since "2026-02-01T00:00:00Z" --until "2026-02-17T23:59:59Z"
 
# Stream logs in real-time (polls every 5 seconds)
auris logs --follow
 
# Output as JSON for piping
auris logs --json | jq '.[] | select(.level == "error")'

Flags:

Flag	Description
`--level <info\|warn\|error>`	Filter by log level
`--action <type>`	Filter by action type (e.g. `user.login`, `role.updated`)
`--since <ISO8601>`	Start of time range
`--until <ISO8601>`	End of time range
`--limit <n>`	Maximum number of entries (default: 50, max: 500)
`--follow`	Poll for new entries every 5 seconds (like `tail -f`)
`--json`	Output as JSON array

`auris generate`

Generate code templates for common integration patterns. Useful for bootstrapping a new project.


# List available templates
auris generate --list


Available templates:
  login-page     Login page with Auris button (React, Next.js, Vue, Svelte)
  callback-page  OAuth2 callback handler page
  middleware     Next.js / Express auth middleware
  api-route      Protected API route handler (Next.js, Express)
  php-login      PHP login flow (login.php + callback.php + dashboard.php)


# Generate a Next.js login page
auris generate login-page --framework nextjs --output ./app/auth/login/page.tsx
 
# Generate an Express middleware
auris generate middleware --framework express --output ./middleware/auth.js
 
# Generate the PHP login flow
auris generate php-login --output ./public/

The generated code is pre-filled with your domain and client ID from .aurisrc.

Scripting

Use --json to get machine-readable output, then pipe it to tools like jq:


# Count users per role
auris users list --json --limit 500 | jq '[.[].roles[]] | group_by(.) | map({role: .[0], count: length})'
 
# Find all disabled accounts
auris users list --json --status disabled | jq '.[] | .email'
 
# Export recent error logs to a file
auris logs --level error --since "2026-02-01T00:00:00Z" --json > errors.json
 
# Delete a test user in a CI teardown step
auris users delete "test-$(echo $BUILD_ID)@example.com" --yes

Exit codes:

Code	Meaning
`0`	Success
`1`	General error
`2`	Configuration error (missing domain, client ID, etc.)
`3`	Authentication error (invalid or expired token)
`4`	Not found (user, role, application does not exist)
`5`	Permission denied (current user lacks the required permission)

Use exit codes in shell scripts to handle errors:


auris users get "[email protected]" --quiet
if [ $? -eq 4 ]; then
  echo "User not found, creating..."
  auris users create --email "[email protected]" --non-interactive
fi

CI/CD Integration

GitHub Actions


# .github/workflows/provision-users.yml
name: Provision users
 
on:
  workflow_dispatch:
 
jobs:
  provision:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Install Auris CLI
        run: npm install -g @auris/cli
 
      - name: Provision users
        env:
          AURIS_DOMAIN: ${{ secrets.AURIS_DOMAIN }}
          AURIS_CLIENT_ID: ${{ secrets.AURIS_CLIENT_ID }}
          AURIS_CLIENT_SECRET: ${{ secrets.AURIS_CLIENT_SECRET }}
          AURIS_TENANT: ${{ secrets.AURIS_TENANT }}
        run: |
          auris users create \
            --email "[email protected]" \
            --first-name "Deploy" \
            --last-name "Bot" \
            --role "ci-runner" \
            --non-interactive

Using a Script File


#!/bin/bash
# provision-tenant.sh
set -e
 
export AURIS_DOMAIN="auth.yourdomain.com"
export AURIS_CLIENT_ID="app_xxxxx"
export AURIS_CLIENT_SECRET="$CI_AURIS_SECRET"
export AURIS_TENANT="my-tenant"
 
echo "Creating roles..."
auris roles create --name "billing-admin" --description "Manages billing"
auris roles create --name "report-viewer" --description "Read-only access to reports"
 
echo "Creating initial admin user..."
auris users create \
  --email "[email protected]" \
  --first-name "Admin" \
  --last-name "User" \
  --role "admin" \
  --send-invite \
  --non-interactive
 
echo "Done."

JavaScript SDK — For programmatic tenant management from Node.js code
REST API Reference — Complete HTTP API for advanced automation
Audit Logs — Log format and available action types

CLI Tool (@auris/cli)

Installation

Authentication

Configuration File (.aurisrc)

Environment Variables

Global Flags

Commands

auris init

auris login

auris whoami

auris test

auris applications list

auris applications create

auris users list

auris users get <id-or-email>

auris users create

auris users update <id-or-email>

auris users delete <id-or-email>

auris roles list

auris roles get <id-or-name>

auris roles create

auris permissions list

auris logs

auris generate

Scripting

CI/CD Integration

GitHub Actions

Using a Script File

Related Pages

Configuration File (`.aurisrc`)

`auris init`

`auris login`

`auris whoami`

`auris test`

`auris applications list`

`auris applications create`

`auris users list`

`auris users get <id-or-email>`

`auris users create`

`auris users update <id-or-email>`

`auris users delete <id-or-email>`

`auris roles list`

`auris roles get <id-or-name>`

`auris roles create`

`auris permissions list`

`auris logs`

`auris generate`