WorkOS CLI

https://github.com/workos/workos-cli
Admin
WorkOS CLI is a command-line interface designed to help developers manage WorkOS organizations and...
Tokens:16,899
Snippets:297
Trust Score:9.9
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Create Organization Examples

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Examples showing how to create organizations with single, multiple, or pending domains.

```bash
# Create organization with one verified domain
workos organization create "Acme Corp" acme.com

# Create organization with pending domain
workos organization create "Acme Corp" acme.com:pending

# Create organization with multiple domains
workos organization create "Acme Corp" acme.com:verified subsidiary.com:pending
```

--------------------------------

### Interactive Add Environment Example

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/environment-command.md

Example session showing the interactive prompts for adding a new environment.

```bash
$ workos env add
Enter a name for the new environment (e.g. local, staging, etc).
> production
Select the type of environment.
> Production
Enter a valid API key for the environment.
> sk_live_abc123
# Output: Environment production added
```

--------------------------------

### Update Organization Examples

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Examples of updating an organization with varying levels of detail.

```bash
# Update organization name only
workos organization update org_abc123 "Acme Corp Renamed"

# Update organization with domain
workos organization update org_abc123 "Acme Corp" acme.com verified

# Update organization with domain (2 args)
workos organization update org_abc123 "Acme Corp" acme.com
```

--------------------------------

### FGA Warrant Creation Examples

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Examples of creating simple warrants, warrants with relations, and warrants with conditional policies.

```bash
# Simple warrant
workos fga warrant create user:john owner document:xyz

# Warrant with relation
workos fga warrant create user:admin#owner owner document:xyz

# Warrant with policy
workos fga warrant create user:john owner document:xyz --policy "region == 'eu'"
```

--------------------------------

### Initialize Table with Headers

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Example of creating a new table and setting headers using the TableHeader function.

```go
tbl := printer.NewTable(80)
tbl = tbl.Headers(
    printer.TableHeader("Column 1"),
    printer.TableHeader("Column 2"),
)
```

--------------------------------

### FGA test output example

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Example output displayed in the terminal after running the test command.

```text
Running tests in schema.test.yaml

✔ Admin is owner
✔ Editor can read
✖ Viewer cannot delete

All tests passed (2/3)
```

--------------------------------

### WorkOS Configuration File Format

Source: https://github.com/workos/workos-cli/blob/main/README.md

Example structure of the .workos.json configuration file.

```json
{
  "environments": {
    "local": {
      "endpoint": "http://localhost:8001",
      "apiKey": "<YOUR_KEY>",
      "type": "Sandbox",
      "name": "local"
    }
  }
}
```

--------------------------------

### Execute Organization List Command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/list-package.md

Examples of using pagination and ordering flags via the CLI.

```bash
# With all pagination flags
workos organization list \
  --limit 20 \
  --after cursor_abc123 \
  --order desc

# With before cursor
workos organization list \
  --limit 10 \
  --before cursor_xyz789 \
  --order asc
```

--------------------------------

### Table Output Example

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

The visual output produced by the table rendering example.

```text
ID          Name        Status
org_123     Acme Corp   Active
org_456     Beta Inc    Inactive
```

--------------------------------

### Define WarrantSetup struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Represents a warrant to be created during the test setup phase.

```go
type WarrantSetup struct {
    Subject  string
    Relation string
    Resource string
    Policy   string
}
```

```yaml
warrants:
  - subject: user:admin
    relation: owner
    resource: doc:1
    policy: "department == 'engineering'"
```

--------------------------------

### FGA test execution examples

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Common usage patterns for running tests on files or directories with optional cleanup.

```bash
# Run single test file
workos fga test schema.test.yaml

# Run all tests in directory
workos fga test ./tests/ --cleanup

# Run with cleanup
workos fga test schema.test.json --cleanup
```

--------------------------------

### Organization List Command Examples

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Common patterns for listing organizations, including filtering by domain, pagination, and sorting.

```bash
# List all organizations
workos organization list

# List with domain filter
workos organization list --domain foo-corp.com

# List with limit and pagination
workos organization list --limit 10 --after cursor123

# List with specific order
workos organization list --order desc --limit 20
```

--------------------------------

### Validate Resource Format

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Examples of correct and incorrect resource identifier formatting.

```bash
# Subject format: type:id or type:id#relation
# Resource format: type:id

# ✓ Valid
workos fga warrant create user:john owner document:xyz

# ✗ Invalid (missing colon)
workos fga warrant create userjohn owner document xyz
```

--------------------------------

### FGA Warrant Creation Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Example output returned after successfully creating a warrant.

```text
Assigned user:john owner document:xyz
Warrant-Token: wt_abc123xyz
```

--------------------------------

### fga check assertion output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Output examples for successful and failed assertions.

```text
✔ assert true user:john owner document:xyz
```

```text
✖ assert true user:john owner document:xyz
# Exits with code 1
```

--------------------------------

### Resource Type List Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Example output format for the resource type list command.

```text
Resource Type
user
document
organization
Before: cursor123
After: cursor456
```

--------------------------------

### Install WorkOS CLI via Homebrew

Source: https://github.com/workos/workos-cli/blob/main/README.md

Use Homebrew to install the WorkOS CLI on MacOS.

```shell
brew install workos/tap/workos-cli
```

--------------------------------

### FGA test file format in JSON

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Structure for defining setup and test cases in JSON format.

```json
{
  "setup": {
    "warrants": [
      {
        "subject": "user:admin",
        "relation": "owner",
        "resource": "doc:1"
      }
    ]
  },
  "tests": [
    {
      "name": "Admin is owner",
      "check": {
        "subject": "user:admin",
        "relation": "owner",
        "resource": "doc:1"
      },
      "expect": true
    }
  ]
}
```

--------------------------------

### FGA Warrant Deletion Example

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Example command to remove a specific warrant.

```bash
workos fga warrant delete user:john owner document:xyz
```

--------------------------------

### Interactive Mode Example

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/init-command.md

Running the command without arguments triggers interactive prompts for environment details.

```bash
$ workos init
# Interactive prompts appear
Enter a name for the new environment (e.g. local, staging, etc).
> local
Select the type of environment.
> Sandbox
Enter a valid API key for the environment.
> sk_test_abc123
# Output: WorkOS CLI initialized
```

--------------------------------

### Non-Interactive Mode Example

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/init-command.md

Providing arguments directly skips the interactive prompts.

```bash
workos init local sk_test_abc123 http://localhost:8001
# Output: WorkOS CLI initialized
```

--------------------------------

### fga check debug output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Example output when using the --debug flag.

```text
✔ Authorized user:john owner document:xyz
Response Time: 42ms
✔ user:john#owner@document:xyz (5ms)
  ✔ user:john owner document:xyz (3ms)
```

--------------------------------

### Organization List Command Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Example output format returned by the organization list command.

```text
ID                                  Name       Domains
org_abc123                          Acme Corp  acme.com, subsidiary.com
org_def456                          Beta Inc   beta.com
Before: cursor456
After: cursor789
```

--------------------------------

### Non-Interactive Add Environment

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/environment-command.md

Example of adding an environment without using interactive prompts.

```bash
workos env add staging sk_test_def456 https://api.staging.workos.com
```

--------------------------------

### FGA Resource List Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Example output format for the resource list command.

```text
Resource Type  Resource ID  Meta
user           john         {"email":"john@example.com"}
user           jane         {"email":"jane@example.com"}
document       doc1         {}
Before: cursor123
After: cursor456
```

--------------------------------

### FGA test file format in YAML

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Structure for defining setup, test cases, and teardown logic in YAML.

```yaml
setup:
  warrants:
    - subject: user:admin
      relation: owner
      resource: doc:1
      policy: "department == 'engineering'"

tests:
  - name: Admin is owner
    check:
      subject: user:admin
      relation: owner
      resource: doc:1
      context:
        department: "engineering"
    expect: true

teardown:
  resources:
    - doc:1
    - user:admin
  warrants:
    - subject: user:admin
      relation: owner
      resource: doc:1
```

--------------------------------

### Get Organization Command Syntax

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Syntax for retrieving details of a specific organization by ID.

```bash
workos organization get <organization_id>
```

--------------------------------

### fga check command examples

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Various ways to invoke the fga check command including context, tokens, and debugging.

```bash
# Simple check
workos fga check user:john owner document:xyz

# Check with context
workos fga check user:john owner document:xyz '{"region":"eu"}'

# Check with warrant token
workos fga check user:john owner document:xyz -w wt_abc123

# Debug check
workos fga check user:john owner document:xyz --debug

# Assert check
workos fga check user:john owner document:xyz --assert true
```

--------------------------------

### FGA Warrant Deletion Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Example output returned after successfully deleting a warrant.

```text
Removed user:john owner document:xyz
Warrant-Token: wt_abc123xyz
```

--------------------------------

### WorkOS CLI Exit Code Examples

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Demonstrates command execution scenarios resulting in success (0) or failure (1) exit codes.

```bash
$ workos organization list
# Exit code 0 (success)

$ workos fga check user:john owner doc:xyz --assert false
# If check returns authorized: Exit code 1 (assertion failed)

$ workos organization get invalid-id
# Exit code 1 (API error)
```

--------------------------------

### Define an FGA Test Specification

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Construct a test specification including setup warrants and individual test cases with expected outcomes.

```go
test := FGATestYaml{
    Setup: FGATestSetupSection{
        Warrants: []WarrantSetup{
            {
                Subject:  "user:admin",
                Relation: "owner",
                Resource: "doc:1",
            },
        },
    },
    Tests: []FGATestCase{
        {
            Name: "Admin is owner",
            Check: FGATestCheck{
                Subject:  "user:admin",
                Relation: "owner",
                Resource: "doc:1",
            },
            Expect: true,
        },
    },
}
```

--------------------------------

### Define FGA Test Structure

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

The FGA test framework supports YAML and JSON formats with defined setup, test, and teardown stages.

```text
Test File (.test.yaml / .test.json)
  ├─ setup
  │  └─ warrants to create
  ├─ tests
  │  ├─ check (subject, relation, resource, context)
  │  └─ expect (true/false)
  └─ teardown
     ├─ warrants to delete
     └─ resources to delete
```

--------------------------------

### Initialize a CLI Configuration

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Create a new configuration object with an active environment and write it to disk.

```go
cfg := config.Config{
    ActiveEnvironment: "local",
    Environments: map[string]config.Environment{
        "local": {
            Name:     "local",
            ApiKey:   "sk_test_123",
            Type:     "Sandbox",
            Endpoint: "http://localhost:8001",
        },
    },
}
err := cfg.Write()
```

--------------------------------

### Define FGA Test Execution Flow

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

The execution sequence for FGA tests involves parsing, setup, test evaluation, teardown, and reporting.

```text
1. Parse test file (YAML or JSON)
2. Run setup: Create warrants and capture WarrantToken
3. Run tests: Evaluate each check with WarrantToken
4. Run teardown: Delete warrants and resources
5. Optional cleanup: Delete setup resources
6. Report results: X/Y tests passed
```

--------------------------------

### Load Configuration

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/configuration.md

Initializes the configuration by reading from the file system and applying environment variable overrides.

```go
cfg := config.LoadConfig()
println(cfg.ActiveEnvironment)
```

--------------------------------

### Initialize and Configure CLI Environments

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

Commands for setting up the CLI and managing multiple environment configurations.

```bash
# Initialize CLI
workos init local sk_test_123

# Add production environment
workos env add production sk_live_456 https://api.workos.com

# Switch to production
workos env switch production
```

--------------------------------

### Command Usage Syntax

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/init-command.md

The basic syntax for executing the init command.

```bash
workos init [name] [api_key] [endpoint]
```

--------------------------------

### Create and Render a Table

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Constructs a table with headers and rows, then renders it to the console.

```go
tbl := printer.NewTable(120)
tbl = tbl.Headers(
    printer.TableHeader("ID"),
    printer.TableHeader("Name"),
    printer.TableHeader("Status"),
)
tbl = tbl.Row("org_123", "Acme Corp", "Active")
tbl = tbl.Row("org_456", "Beta Inc", "Inactive")
printer.PrintMsg(tbl.Render())
```

--------------------------------

### Execute CLI

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/cli-root-command.md

The main entry point for the CLI, responsible for initializing configuration and processing arguments.

```go
func Execute()
```

```go
func main() {
    cmd.SetVersion("dev")
    cmd.Execute()
}
```

--------------------------------

### Initialize or Switch Environment

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Resolves configuration errors by initializing the CLI or switching to a valid environment.

```bash
# Solution: Initialize the CLI
workos init

# Or: Switch to an existing environment
workos env switch
```

--------------------------------

### Command Initialization

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

Initializes the command configuration and SDK credentials, typically called by cobra.OnInitialize.

```go
// Called by cobra.OnInitialize
func initConfig() {
    cmdConfig = config.LoadConfig()
    // Set SDK credentials
}
```

--------------------------------

### Initialize WorkOS SDK Clients

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

Configures API keys and optional custom endpoints for the organizations and FGA SDK clients.

```go
initConfig() {
    // Set API keys on default clients
    organizations.SetAPIKey(apiKey)
    fga.SetAPIKey(apiKey)
    
    // Override endpoints if configured
    if endpoint != "" {
        organizations.DefaultClient.Endpoint = endpoint
        fga.DefaultClient.Endpoint = endpoint
    }
}
```

--------------------------------

### Resolve Configuration Initialization Errors

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Commands to address environment configuration issues.

```bash
# If you see "no active environment configured"
workos init

# If you see "configured active environment is invalid"
workos env switch
```

--------------------------------

### Initialize New Table

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Defines the signature for creating a new table with a specified character width.

```go
func NewTable(width int) *table.Table
```

--------------------------------

### CLI Execution Flow

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

Visual representation of the synchronous lifecycle from startup to exit.

```text
startup
  ↓
config initialization
  ↓
command parsing
  ↓
command execution
  ↓
output
  ↓
exit
```

--------------------------------

### Troubleshoot API Authentication Errors

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Steps to verify environment settings and update expired API keys.

```bash
# Check active environment
workos env switch

# Verify API key is valid
# If still getting auth errors, the API key may be expired
# Generate a new one and run:
workos env add <name> <new_api_key>
workos env switch <name>
```

--------------------------------

### Provide API Key for Init

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Resolves missing API key errors during initialization by providing the key as an argument or using interactive mode.

```bash
# Provide the API key as the second argument
workos init local sk_test_abc123

# Or run in interactive mode
workos init
```

--------------------------------

### Create Organization Command Syntax

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Syntax for creating a new organization with optional domain specifications.

```bash
workos organization create <name> [domain]:[state] [domain]:[state]...
```

--------------------------------

### Configuration Loading

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

Loads the application configuration from the internal config package.

```go
// Load configuration
cfg := config.LoadConfig()
```

--------------------------------

### List Resource Types

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Command to list existing resource types with optional pagination flags.

```bash
workos fga resourcetype list [flags]
```

--------------------------------

### Apply Resource Types

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Commands to apply resource type definitions from a file or stdin.

```bash
workos fga resourcetype apply -f <file>
workos fga resourcetype apply < <file>
```

--------------------------------

### Initialize WorkOS CLI

Source: https://github.com/workos/workos-cli/blob/main/README.md

Run the initialization command to configure the CLI for a specific environment.

```shell
workos init
```

--------------------------------

### Success Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/init-command.md

The console output displayed upon successful initialization.

```text
creating ~/.workos.json
WorkOS CLI initialized
```

--------------------------------

### Command Entry Point

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

The main function for the CLI application, responsible for setting the version and executing commands.

```go
// Application entry point
func main() {
    cmd.SetVersion("dev")
    cmd.Execute()
}
```

--------------------------------

### Write Configuration to File

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/configuration.md

Persists the current configuration to ~/.workos.json.

```go
cfg := config.Config{
    ActiveEnvironment: "local",
    Environments: map[string]config.Environment{
        "local": {
            Name:     "local",
            ApiKey:   "sk_test_123",
            Type:     "Sandbox",
            Endpoint: "http://localhost:8001",
        },
    },
}
err := cfg.Write()
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Define Configuration Structs

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

Defines the structure for managing active environments and environment-specific settings.

```go
type Config struct {
    ActiveEnvironment string
    Environments      map[string]Environment
}

type Environment struct {
    Endpoint string
    Name     string
    Type     string  // "Production" or "Sandbox"
    ApiKey   string
}
```

--------------------------------

### Define Config Struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/configuration.md

Represents the complete CLI configuration structure.

```go
type Config struct {
    ActiveEnvironment string
    Environments      map[string]Environment
}
```

--------------------------------

### Define Configuration Constants

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/configuration.md

Standard constants used for environment variable prefixes and file naming conventions.

```go
const (
    EnvVarPrefix       = "WORKOS"
    EnvVarHeadlessMode = "headless"
    FilePrefix         = ".workos"
    FileExtension      = "json"
    FileName           = ".workos.json"
)
```

--------------------------------

### NewTable

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Creates a new formatted table instance for CLI output.

```APIDOC
## NewTable

### Description
Creates a new formatted table configured with a normal border style and enabled header borders.

### Signature
`func NewTable(width int) *table.Table`

### Parameters
- **width** (int) - Required - The width of the table in characters.

### Returns
- `*table.Table` - A configured table object from the lipgloss package.

### Example
```go
tbl := printer.NewTable(120)
tbl = tbl.Headers(printer.TableHeader("ID"), printer.TableHeader("Name"))
tbl = tbl.Row("org_123", "Acme Corp")
printer.PrintMsg(tbl.Render())
```
```

--------------------------------

### Render Table Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Iterates through items to populate and render a full table.

```go
tbl := printer.NewTable(150)
tbl = tbl.Headers(
    printer.TableHeader("ID"),
    printer.TableHeader("Name"),
)
for _, item := range items {
    tbl = tbl.Row(item.ID, item.Name)
}
printer.PrintMsg(tbl.Render())
```

--------------------------------

### Troubleshoot Organization API Failures

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Steps to verify API keys, organization existence, and ID formatting when API operations fail.

```bash
# Check API key
workos env list  # View active environment
echo $WORKOS_ACTIVE_ENVIRONMENT  # Check env var

# Check organization exists
workos organization list

# Check organization ID format (should be org_xxx)
workos organization get org_abc123
```

--------------------------------

### Retrieve Configuration

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/cli-root-command.md

Retrieves the active configuration or terminates the process if validation fails.

```go
func GetConfigOrExit() *config.Config
```

```go
cfg := cmd.GetConfigOrExit()
// cfg.ActiveEnvironment will be set
// cfg.Environments will contain at least one environment
```

--------------------------------

### Define Environment Struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/configuration.md

Represents a single WorkOS environment configuration.

```go
type Environment struct {
    Endpoint string
    Name     string
    Type     string
    ApiKey   string
}
```

--------------------------------

### Set CLI Version

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/cli-root-command.md

Sets the version string displayed when running the CLI with the --version flag.

```go
func SetVersion(version string)
```

```go
cmd.SetVersion("1.0.0")
```

--------------------------------

### Manage Organizations

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

Commands for creating, listing, updating, and deleting organization entities.

```bash
# Create organization
workos organization create "Acme Corp" acme.com

# List organizations
workos organization list --limit 10 --order desc

# Update organization
workos organization update org_123 "New Name"

# Delete organization
workos organization delete org_123
```

--------------------------------

### Base Organization Command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

The entry point for all organization-related operations.

```bash
workos organization [subcommand]
```

--------------------------------

### Register Cobra commands and flags

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

Use the init function to attach subcommands to the root command and define command-specific flags.

```go
func init() {
    // Register command with parent
    rootCmd.AddCommand(initCmd)
    
    // Register flags
    initCmd.Flags().String(FlagEndpoint, "", "Override endpoint")
}

var initCmd = &cobra.Command{
    Use:   "init",
    Short: "Initialize the CLI",
    RunE: func(cmd *cobra.Command, args []string) error {
        // Command implementation
        return nil
    },
}
```

--------------------------------

### Manage WorkOS Environments

Source: https://github.com/workos/workos-cli/blob/main/README.md

Commands for adding, switching, and removing WorkOS environments.

```shell
workos env add
```

```shell
workos env switch
```

```shell
workos env remove
```

--------------------------------

### Configure Headless Mode

Source: https://github.com/workos/workos-cli/blob/main/README.md

Set environment variables to configure the CLI in headless mode.

```shell
export WORKOS_ACTIVE_ENVIRONMENT=headless
export WORKOS_ENVIRONMENTS_HEADLESS_NAME=local
export WORKOS_ENVIRONMENTS_HEADLESS_ENDPOINT=http://localhost:8001
export WORKOS_ENVIRONMENTS_HEADLESS_API_KEY=<YOUR_KEY>
export WORKOS_ENVIRONMENTS_HEADLESS_TYPE=Sandbox
```

--------------------------------

### FGA Resource Creation Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Expected console output after executing the resource creation command.

```text
Created resource user:john
```

```text
Created resource user:john ({"email":"john@example.com","role":"admin"})
```

--------------------------------

### Base Environment Command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/environment-command.md

Displays the base usage pattern for the environment management command.

```bash
workos env [subcommand]
```

--------------------------------

### Organization List Command Usage

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Basic syntax for executing the organization list command.

```bash
workos organization list [flags]
```

--------------------------------

### Print Message

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Prints a string message to stdout.

```go
printer.PrintMsg("Organization created successfully")
// Output: Organization created successfully
```

--------------------------------

### Add Environment with API Key

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Resolves missing API key errors when adding an environment by providing the key or using interactive mode.

```bash
# Provide all required arguments
workos env add staging sk_test_def456

# Or run in interactive mode
workos env add
```

--------------------------------

### Base FGA Command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

The entry point for all FGA-related operations in the CLI.

```bash
workos fga [subcommand]
```

--------------------------------

### Register Flags in init Function

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/list-package.md

Standard pattern for registering list flags within a command's init function.

```go
func init() {
    listOrgCmd.Flags().String(list.FlagAfter, "", "Cursor for results after a specific item")
    listOrgCmd.Flags().String(list.FlagBefore, "", "Cursor for results before a specific item")
    listOrgCmd.Flags().Int(list.FlagLimit, 0, "Limit the number of results")
    listOrgCmd.Flags().String(list.FlagOrder, "", "Order of results (asc or desc)")
}
```

--------------------------------

### Create Organization JSON Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

The expected JSON response structure after successfully creating an organization.

```json
{
    "id": "org_abc123",
    "name": "Acme Corp",
    "domains": [
        {
            "domain": "acme.com",
            "state": "verified"
        }
    ]
}
```

--------------------------------

### Define Color Rendering Functions

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Defines global style functions for terminal output using lipgloss. These functions return a string rendering of the applied style.

```go
var GreenText = lipgloss.NewStyle().Foreground(lipgloss.Color("#00FF00")).Render
var RedText = lipgloss.NewStyle().Foreground(lipgloss.Color("#FF0000")).Render
var YellowText = lipgloss.NewStyle().Foreground(lipgloss.Color("#FFCC00")).Render
var TableHeader = YellowText
```

--------------------------------

### Define FGATestTeardownSection struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Specifies resources and warrants to be cleaned up after test completion.

```go
type FGATestTeardownSection struct {
    Warrants  []WarrantSetup
    Resources []string
}
```

```yaml
teardown:
  resources:
    - user:john
    - document:xyz
  warrants:
    - subject: user:john
      relation: owner
      resource: document:xyz
```

--------------------------------

### List FGA Resources

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Lists resources with support for filtering by type, search terms, and pagination.

```bash
workos fga resource list [flags]
```

```bash
workos fga resource list --type=user --limit=15
workos fga resource list --search=john --order=asc
```

--------------------------------

### Define FGATestSetupSection struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Container for a collection of warrants to be created before test execution.

```go
type FGATestSetupSection struct {
    Warrants []WarrantSetup
}
```

--------------------------------

### Project Module Structure

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

Visual representation of the WorkOS CLI directory layout and primary source files.

```text
github.com/workos/workos-cli/
├── cmd/workos/
│   └── main.go              ← Application entry point
├── internal/
│   ├── cmd/                 ← Command implementations
│   │   ├── root.go
│   │   ├── init.go
│   │   ├── environment.go
│   │   ├── organization.go
│   │   └── fga.go
│   ├── config/              ← Configuration management
│   │   └── config.go
│   ├── printer/             ← Output formatting
│   │   └── printer.go
│   └── list/                ← Pagination constants
│       └── list.go
├── go.mod
├── go.sum
└── .goreleaser.yaml
```

--------------------------------

### Create FGA Resource

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Creates a new resource with an optional JSON metadata object.

```bash
workos fga resource create <resource> [metadata]
```

```bash
# Simple resource
workos fga resource create user:john

# Resource with metadata
workos fga resource create user:john '{"email":"john@example.com","role":"admin"}'
```

--------------------------------

### Print Success Message

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Displays a green success message with a checkmark icon.

```go
printer.PrintMsg(fmt.Sprintf(
    "%s %s",
    printer.GreenText(printer.Checkmark, "Success"),
    "Organization created",
))
```

--------------------------------

### Define Environment Structure

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

Represents an individual environment configuration, including API credentials and endpoint details.

```go
type Environment struct {
    Endpoint string
    Name     string
    Type     string  // "Production" or "Sandbox"
    ApiKey   string
}
```

--------------------------------

### Define and use FGATestResult struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Represents the outcome of a test run.

```go
type FGATestResult struct {
    Passed    bool
    NumPassed int
    NumTotal  int
}
```

```go
result := FGATestResult{
    Passed:    true,
    NumPassed: 5,
    NumTotal:  5,
}
// Output: "All tests passed (5/5)"
```

--------------------------------

### Add Environment Command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/environment-command.md

Syntax for adding a new environment via command-line arguments.

```bash
workos env add [name] [api_key] [endpoint]
```

--------------------------------

### Handle API Call Failures

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Verify resource existence and credentials when API calls fail.

```bash
# List available resource types
workos fga resourcetype list

# Check resource exists before operations
workos fga resource list --type user

# Verify warrant exists
workos fga check user:john owner document:xyz
```

--------------------------------

### Environment Constants

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/environment-command.md

Defines the regex pattern for environment names and the supported environment types and flag names.

```go
const (
    EnvironmentNameRegex      = `[a-z0-9\-_]+`
    EnvironmentTypeProduction = "Production"
    EnvironmentTypeSandbox    = "Sandbox"
    FlagEndpoint              = "endpoint"
)
```

--------------------------------

### Define and use FGATestCheck struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Specifies the permission check parameters for a test case.

```go
type FGATestCheck struct {
    Subject  string
    Relation string
    Resource string
    Context  map[string]interface{}
}
```

```go
check := FGATestCheck{
    Subject:  "user:john",
    Relation: "owner",
    Resource: "document:xyz",
    Context: map[string]interface{}{
        "region": "eu",
        "department": "engineering",
    },
}
```

--------------------------------

### Execute Organization Create Command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

The command execution flow for creating a new organization via the CLI.

```text
$ workos organization create "Acme" acme.com

1. Parse args: name="Acme", domain="acme.com"
2. Build OrganizationDomainData slice
3. Call organizations.CreateOrganization(ctx, opts)
4. Receive *organizations.Organization response
5. Format with printer.PrintJson()
```

--------------------------------

### CLI Command Structure

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/cli-root-command.md

The basic syntax for invoking the WorkOS CLI.

```bash
workos [command] [args]
```

--------------------------------

### Handle Invalid Resource Format

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Ensure resources follow the type:id format.

```bash
# Correct format
workos fga resource create document:xyz
workos fga warrant create user:john owner document:xyz
```

--------------------------------

### Apply Command Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Confirmation message returned after a successful apply operation.

```text
Resource types updated
```

--------------------------------

### Define Output Symbols

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Platform-adaptive symbols used for CLI status indicators.

```go
var Checkmark = "✔"     // Platform-adaptive
var Cross = "✖"          // Platform-adaptive
var QuestionMark = "?"   // Constant
```

--------------------------------

### Define FGA test case structure with marshaling tags

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Use struct tags to enable JSON and YAML serialization for FGA test cases.

```go
type FGATestCase struct {
    Name   string       `yaml:"name" json:"name"`
    Check  FGATestCheck `yaml:"check" json:"check"`
    Expect bool         `yaml:"expect" json:"expect"`
}
```

--------------------------------

### Add Environment with Valid Name

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Resolves invalid environment name errors during the add operation.

```bash
# Use valid environment name format
workos env add staging-env sk_test_123
```

--------------------------------

### Execute FGA tests command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Basic syntax for running FGA tests via the WorkOS CLI.

```bash
workos fga test <test_file.test.yaml|json|directory> [flags]
```

--------------------------------

### Define Pagination and Filtering Constants

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/list-package.md

Constants used to define pagination and filtering flags across the CLI.

```go
const (
    FlagAfter  = "after"
    FlagBefore = "before"
    FlagLimit  = "limit"
    FlagOrder  = "order"
)
```

--------------------------------

### Define FGATestYaml struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Root container for the complete FGA test specification.

```go
type FGATestYaml struct {
    Setup    FGATestSetupSection
    Tests    []FGATestCase
    Teardown *FGATestTeardownSection
}
```

```yaml
setup:
  warrants:
    - subject: user:admin
      relation: owner
      resource: doc:1

tests:
  - name: Admin is owner
    check:
      subject: user:admin
      relation: owner
      resource: doc:1
    expect: true
  - name: User is not owner
    check:
      subject: user:john
      relation: owner
      resource: doc:1
    expect: false

teardown:
  resources:
    - user:admin
    - user:john
    - doc:1
```

--------------------------------

### Enable verbose output for schema application

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Use the --verbose flag to see details about resource types being applied during schema updates.

```bash
workos fga schema apply schema.txt --verbose
```

--------------------------------

### Override API Endpoint

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/environment-command.md

Demonstrates using the --endpoint flag to specify a custom API URL when adding an environment.

```bash
workos env add staging sk_test_123 --endpoint https://api.staging.workos.com
```

--------------------------------

### Print Colored Messages

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Demonstrates usage of color functions to print success, error, and warning messages to the console.

```go
printer.PrintMsg(printer.GreenText(printer.Checkmark, "Operation successful"))
printer.PrintMsg(printer.RedText(printer.Cross, "Operation failed"))
printer.PrintMsg(printer.YellowText("Warning: deprecated feature"))
```

--------------------------------

### Switch the active environment

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/environment-command.md

Switches the active environment to the specified name or via interactive selection.

```bash
workos env switch [name]
```

```text
Select an environment.
> local [http://localhost:8001]
> staging [Sandbox]
> production [Production] [https://api.production.workos.com]
```

```bash
workos env switch production
```

```bash
$ workos env switch
Select an environment.
> local [http://localhost:8001]
  staging [Sandbox]
  production [Production]
# User selects 'production'
# Output: Switched to environment production [Production]
```

--------------------------------

### Perform FGA Operations

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

Commands for managing warrants, checking permissions, querying resources, and running tests.

```bash
# Create warrant
workos fga warrant create user:john owner document:xyz

# Check permission
workos fga check user:john owner document:xyz

# Query resources
workos fga query "select document where user:john is owner"

# Run tests
workos fga test permissions.test.yaml --cleanup
```

--------------------------------

### Update Organization Command Syntax

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Syntax for updating an organization's name, domain, and verification state.

```bash
workos organization update <organization_id> <name> [domain] [state]
```

--------------------------------

### Handle Schema Validation Errors

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Validate schema files and use correct file extensions before applying.

```bash
# Validate schema before applying
workos fga schema validate schema.txt

# Check schema syntax
workos fga schema convert schema.txt --to json --output pretty

# Use correct file extensions
# Valid: .txt, .yaml, .yml, .json, .test.yaml, .test.json
workos fga schema apply my-schema.txt
```

--------------------------------

### PrintJson(val any)

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Prints a Go value as formatted JSON to stdout with 4-space indentation.

```APIDOC
## PrintJson(val any)

### Description
Prints a Go value as formatted JSON to stdout. If marshaling fails, the process exits with error code 1.

### Parameters
- **val** (any) - Required - The value to encode and print.

### Example
```go
org := Organization{ID: "org_123", Name: "Acme Corp"}
printer.PrintJson(org)
```
```

--------------------------------

### Execute WorkOS CLI Commands

Source: https://github.com/workos/workos-cli/blob/main/README.md

General syntax for executing commands with the WorkOS CLI.

```shell
workos [cmd] [args]
```

--------------------------------

### Print Warning Message

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Displays a simple yellow warning message.

```go
printer.PrintMsg(printer.YellowText("Warning: This operation cannot be undone"))
```

--------------------------------

### Test File Format

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/INDEX.md

The YAML structure for test files, supporting .test.yaml, .test.yml, and .test.json extensions.

```yaml
setup:
  warrants:
    - subject: user:admin
      relation: owner
      resource: doc:1

tests:
  - name: Admin is owner
    check:
      subject: user:admin
      relation: owner
      resource: doc:1
    expect: true

teardown:
  resources:
    - doc:1
    - user:admin
```

--------------------------------

### Print JSON Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Formats a Go value as indented JSON and prints to stdout. Exits with code 1 if marshaling fails.

```go
org := Organization{
    ID:   "org_123",
    Name: "Acme Corp",
}
printer.PrintJson(org)
// Output:
// {
//     "id": "org_123",
//     "name": "Acme Corp"
// }
```

--------------------------------

### Handle Test File Errors

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Use accepted test file extensions and ensure test names are unique.

```bash
# Use correct file extension
workos fga test permissions.test.yaml

# Ensure unique test names
# ❌ Wrong: two tests named "Admin test"
# ✅ Right: "Admin is owner", "Admin can edit"

# Test directory of files
workos fga test ./tests/  # All *.test.yaml/*.test.json files

# Validate test file format
workos fga test --cleanup schema.test.yaml
```

--------------------------------

### Implement Error Wrapping in Go

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

Use this pattern to wrap errors with contextual information before returning them to the caller.

```go
if err != nil {
    return errors.Wrap(err, "context about what failed")
}
```

--------------------------------

### Convert FGA schemas

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Convert between schema text files and JSON resource type formats using the schema convert command.

```bash
workos fga schema convert schema.txt --to json
```

```bash
workos fga schema convert resource-types.json --to schema --output raw
```

--------------------------------

### Define FGATestCase struct

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/types.md

Defines a single test case including the check to perform and the expected boolean result.

```go
type FGATestCase struct {
    Name   string
    Check  FGATestCheck
    Expect bool
}
```

```yaml
tests:
  - name: Admin is owner
    check:
      subject: user:admin
      relation: owner
      resource: doc:1
      context:
        region: eu
    expect: true
```

--------------------------------

### Query access rules with WorkOS CLI

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Use the fga query command to check access rules. Context can be provided as a JSON string.

```bash
workos fga query "select document where user:john is owner"
```

```bash
workos fga query "select user where $ is owner of document:xyz"
```

```bash
workos fga query "select document where user:john is owner" '{"region":"us"}'
```

--------------------------------

### Create FGA Warrant Command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Syntax for creating a new warrant with required subject, relation, and resource arguments.

```bash
workos fga warrant create <subject> <relation> <resource> [flags]
```

--------------------------------

### Exported Constants

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/init-command.md

Constants used for environment configuration and validation.

```go
const (
    FlagEndpoint              = "endpoint"
    EnvironmentNameRegex      = `[a-z0-9\-_]+`
    EnvironmentTypeProduction = "Production"
    EnvironmentTypeSandbox    = "Sandbox"
)
```

--------------------------------

### Register Command Flags

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/list-package.md

Standard implementation for registering pagination flags on a cobra command.

```go
listCmd.Flags().String(list.FlagAfter, "", "Cursor for results after a specific item")
listCmd.Flags().String(list.FlagBefore, "", "Cursor for results before a specific item")
listCmd.Flags().Int(list.FlagLimit, 0, "Limit the number of results")
listCmd.Flags().String(list.FlagOrder, "", "Order of results (asc or desc)")
```

--------------------------------

### FGA Resource Update Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Expected console output after updating a resource.

```text
Updated resource user:john
```

--------------------------------

### workos fga resource create

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Creates a new FGA resource with an optional metadata JSON object.

```APIDOC
## workos fga resource create

### Description
Creates a new resource in the system.

### Usage
`workos fga resource create <resource> [metadata]`

### Arguments
- **resource** (string) - Required - Resource in format `type:id`
- **metadata** (string) - Optional - JSON metadata object

### Example
`workos fga resource create user:john '{"email":"john@example.com","role":"admin"}'`
```

--------------------------------

### Define Table Header

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Function signature for creating a yellow-colored table header string.

```go
func TableHeader(text string) string
```

--------------------------------

### Resolve Non-Existent Environment Errors

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Resolves errors when an environment does not exist by listing available environments or using a known name.

```bash
# Check available environments
workos env switch  # Shows interactive list

# Or use a known environment name
workos env remove local  # if local exists
```

--------------------------------

### Set Active Environment via Environment Variable

Source: https://github.com/workos/workos-cli/blob/main/README.md

Set the active environment using the WORKOS_ACTIVE_ENVIRONMENT variable.

```shell
export WORKOS_ACTIVE_ENVIRONMENT=local
```

--------------------------------

### Correct Organization List Flags

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Resolves flag parsing errors by using correct syntax and types for organization list commands.

```bash
# Use correct flag syntax and types
workos organization list --limit 10 --order asc

# Use double quotes for flag values
workos organization list --domain "example.com"
```

--------------------------------

### Define flag constants

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

Constant definition for the domain flag used in organization commands.

```go
const (
    FlagDomain = "domain"
)
```

--------------------------------

### Print Error and Exit

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Prints an error message to stderr and terminates the process with exit code 1.

```go
printer.PrintErrAndExit("Invalid organization ID")
// Output (stderr): Error: Invalid organization ID
// Exits with code 1
```

--------------------------------

### Execute FGA Check Command

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

The command execution flow for performing an FGA authorization check.

```text
$ workos fga check user:john owner doc:xyz --debug

1. Parse args: subject, relation, resource
2. Parse optional flags: warrantToken, debug
3. Build WarrantCheck struct
4. Call fga.Check(ctx, CheckOpts)
5. Format result (Authorized/Not Authorized)
6. If debug: Print decision tree from DebugInfo
```

--------------------------------

### Organization Update Output Format

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/organization-command.md

The JSON structure returned after a successful organization update.

```json
{
    "id": "org_abc123",
    "name": "Acme Corp Renamed",
    "domains": [
        {
            "domain": "acme.com",
            "state": "verified"
        }
    ]
}
```

--------------------------------

### workos fga resource list

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Lists FGA resources with support for filtering, searching, and pagination.

```APIDOC
## workos fga resource list

### Description
Lists resources with optional filtering and pagination.

### Usage
`workos fga resource list [flags]`

### Flags
- **--type** (string) - Filter by resource type
- **--search** (string) - Search term
- **--limit** (int) - Maximum number of results (default: 10)
- **--before** (string) - Pagination cursor
- **--after** (string) - Pagination cursor
- **--order** (string) - Sort order (asc or desc)

### Example
`workos fga resource list --type=user --limit=15`
```

--------------------------------

### Define CLI Integration Flow

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/architecture.md

The standard data flow from CLI command input through the WorkOS Go SDK to the final formatted output.

```text
CLI Command → Parser → Struct Builder → WorkOS SDK Call → Result → Formatter
```

--------------------------------

### Print Error Message

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Displays a red error message with a cross icon.

```go
printer.PrintMsg(fmt.Sprintf(
    "%s %s",
    printer.RedText(printer.Cross, "Error"),
    "Failed to update organization",
))
```

--------------------------------

### Resource Type JSON Input Format

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

The expected JSON array structure for defining resource types.

```json
[
    {
        "type": "user",
        "relations": {
            "owner": {}
        }
    },
    {
        "type": "document",
        "relations": {
            "owner": {},
            "reader": {}
        }
    }
]
```

--------------------------------

### Remove an environment

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/environment-command.md

Removes a configured environment by name or via interactive prompt.

```bash
workos env remove [name]
```

```bash
workos env remove staging
# Output: Environment staging removed
```

--------------------------------

### FGA Resource Delete Output

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Expected console output after deleting a resource.

```text
Deleted resource user:john
```

--------------------------------

### Validate Environment Name Format

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Ensures environment names follow the required lowercase alphanumeric format with hyphens or underscores.

```bash
# Use only lowercase, numbers, hyphens, underscores
workos init prod-us-east-1 sk_test_123
```

--------------------------------

### Define FGATestCheck structure

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Defines the check parameters for an FGA test case.

```go
type FGATestCheck struct {
    Subject  string
    Relation string
    Resource string
    Context  map[string]interface{}
}
```

--------------------------------

### Assert authorization results

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Use the --assert flag to force the command to exit with code 1 if the user is not authorized.

```bash
workos fga check user:john owner document:xyz --assert true
```

--------------------------------

### fga check command syntax

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Basic command structure for checking subject relations.

```bash
workos fga check <subject> <relation> <resource> [context] [flags]
```

--------------------------------

### FGA Constants

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/fga-command.md

Separator constants used for resource and relation definitions.

```go
const (
    ResourceSeparator = ":"
    RelationSeparator = "#"
)
```

--------------------------------

### Upgrade WorkOS CLI via Homebrew

Source: https://github.com/workos/workos-cli/blob/main/README.md

Use Homebrew to upgrade the WorkOS CLI on MacOS.

```shell
brew upgrade workos/tap/workos-cli
```

--------------------------------

### Enable debug output for FGA checks

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/errors.md

Use the --debug flag to display the decision tree and processing time for FGA checks.

```bash
workos fga check user:john owner document:xyz --debug
```

--------------------------------

### PrintMsg(msg string)

Source: https://github.com/workos/workos-cli/blob/main/_autodocs/api-reference/printer.md

Prints a provided string message to stdout.

```APIDOC
## PrintMsg(msg string)

### Description
Prints a message to stdout.

### Parameters
- **msg** (string) - Required - The message to print.

### Example
```go
printer.PrintMsg("Organization created successfully")
```
```
Tokens:
Raw