housectl Command Reference

housectl is the command-line interface for the housecarl authorization system. It provides comprehensive tools for managing tenants, users, domains, policies, API keys, and performing authorization checks.

Installation

Build with Bazel:

./bzsh build //housecarl/src/bin:housectl

Or use the Makefile shortcut:

make cli

Binary location: ./bazel-bin/housecarl/src/bin/housectl

Quick Start

# 1. Login to a housecarl server
housectl config login https://housecarl.example.com root

# 2. Check basic connectivity
housectl config health

# 3. Explore available commands
housectl <COMMAND> --help

Global Options

These options are available for all commands:

Option	Description
`--context <NAME>`	Use a specific context for this command (overrides HOUSECARL_CONTEXT)
`--config <FILE>`	Path to configuration file (overrides default location)
`--log-level <LEVEL>`	Logging verbosity: 0=error, 1=warn, 2=info, 3=debug, 4=trace
`-o, --format <FORMAT>`	Output format: `pretty` (default), `table`, or `json`
`--interface-version`	Print interface version and exit (for scripting compatibility)
`--auto-refresh`	Automatically refresh JWT if it will expire soon (uses `HOUSECTL_PASSWORD`)
`--help`	Display help information
`--version`	Display version information

Environment Variables

Variable	Description	Priority
`HOUSECARL_ENDPOINT`	Direct endpoint override (requires HOUSECARL_TOKEN)	Highest
`HOUSECARL_TOKEN`	Direct token override (requires HOUSECARL_ENDPOINT)	Highest
`HOUSECARL_CONTEXT`	Context name to use (overrides config default)	Medium
`HOUSECARL_CONFIG_PATH`	Custom config file path (must be absolute)	N/A
`HOUSECARL_PASSWORD`	Password for login (avoids interactive prompt)	N/A
`HOUSECTL_PASSWORD`	Password used for `--auto-refresh` token refresh	N/A

Precedence Order (highest to lowest):

HOUSECARL_ENDPOINT + HOUSECARL_TOKEN (direct connection, bypasses config)
--context CLI flag
HOUSECARL_CONTEXT environment variable
current context from config file

Configuration

Configuration File Location

All Platforms: ~/.config/housecarl.toml

Configuration File Structure (Multi-Context TOML)

current = "admin@acme@localhost"

[contexts.admin@acme@localhost]
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
endpoint = "http://localhost:50051"
user_id = "7c9e6679-7425-40de-944b-e07fc1f90ae7"
username = "admin"
tenant_id = "550e8400-e29b-41d4-a716-446655440000"

[contexts.devuser@staging@staging-server]
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
endpoint = "https://staging.example.com:50051"
user_id = "8c9e6679-7425-40de-944b-e07fc1f90ae8"
username = "devuser"
tenant_id = "660e8400-e29b-41d4-a716-446655440001"

Configuration Fields:

current: Name of the currently active context
contexts: Map of context configurations by name
- Context names are auto-generated in format username@tenant@host
- token: JWT authentication token (obtained from login)
- tenant_id: UUID of the tenant (optional if you logged in without a tenant)
- user_id: UUID of the authenticated user
- endpoint: gRPC endpoint URL
- username: Username for display purposes

Commands

config

Authentication and connection configuration commands.

Authenticate with a housecarl server and establish a session.

Usage:

housectl config login <ENDPOINT> <USERNAME> [OPTIONS]

Arguments:

<ENDPOINT> - Server URL (gRPC endpoint, e.g., https://housecarl.example.com or http://localhost:50051)
<USERNAME> - Username for authentication

Options:

--tenant <TENANT> - Tenant ID or name to authenticate against
--password <PASSWORD> - Password (or set HOUSECARL_PASSWORD env var; will prompt if not provided)
--duration <SECONDS> - Session token validity in seconds (default: 43200 = 12 hours)
--as <CONTEXT_NAME> - Use custom context name instead of auto-generated one

Examples:

# Bootstrap or admin login
housectl config login https://housecarl.example.com root

# Login with password from environment variable
export HOUSECARL_PASSWORD=Secret123!
housectl config login http://localhost:50051 alice

# Login directly into a tenant-scoped session once the user is associated
housectl config login http://localhost:50051 alice --tenant acme-corp --password Secret123!

# Login with custom token duration (24 hours)
housectl config login https://housecarl.example.com root --duration 86400

# Login with custom context name
housectl config login http://localhost:50051 admin --as my-local-dev

Notes:

On successful login, a signed JWT token is stored locally
Token is used for subsequent commands
Password can be provided via flag, environment variable, or interactive prompt
--tenant is optional; start without it for bootstrap, health checks, and root-admin workflows
Some deployments only issue tenant-scoped sessions after the user is already associated with that tenant

config logout

Clear stored credentials and end the current session.

Usage:

housectl config logout

Example:

housectl config logout

config status

Display current authentication status and configuration details.

Usage:

housectl config status

Example:

housectl config status

Output includes:

Configuration file path
Server URL
Tenant ID
User ID
Username
Token timestamps (exp, nbf, iat) in pretty format

config ping

Verify connection to the server with current credentials.

Usage:

housectl config ping

Example:

housectl config ping

Notes:

Use this to verify a tenant-scoped session is still valid
For basic reachability or tenantless sessions, prefer housectl config health

config health

Check server health status.

Usage:

housectl config health [OPTIONS]

Options:

--watch - Continuously monitor health status (stream updates until Ctrl+C)

Examples:

# Single health check
housectl config health

# Continuous health monitoring
housectl config health --watch

Health Status Codes:

0 - UNKNOWN
1 - SERVING
2 - NOT_SERVING
3 - SERVICE_UNKNOWN

config list

List all available contexts.

Usage:

housectl config list

Example:

housectl config list

Output:

CONTEXT NAME                    ENDPOINT                         CURRENT
admin@acme@localhost            http://localhost:50051           *
devuser@staging@staging-server  https://staging.example.com:50051

config current

Show the current active context name.

Usage:

housectl config current

Example:

housectl config current

Output:

admin@acme@localhost

config use

Switch to a different context.

Usage:

housectl config use <CONTEXT_NAME>

Arguments:

<CONTEXT_NAME> - Name of the context to switch to

Example:

housectl config use devuser@staging@staging-server

Notes:

Use housectl config list to see available contexts
The context must exist in the configuration file

config show

Show details of a specific context.

Usage:

housectl config show <CONTEXT_NAME>

Arguments:

<CONTEXT_NAME> - Name of the context to show details for

Example:

housectl config show admin@acme@localhost

Output:

Context: admin@acme@localhost
  Endpoint: http://localhost:50051
  Username: admin
  User ID:  7c9e6679-7425-40de-944b-e07fc1f90ae7
  Tenant:   550e8400-e29b-41d4-a716-446655440000

config remove

Remove a context from the configuration.

Usage:

housectl config remove <CONTEXT_NAME>

Arguments:

<CONTEXT_NAME> - Name of the context to remove

Example:

housectl config remove old-context

Notes:

Cannot remove the current active context
Use housectl config use to switch contexts first

user

User account management commands.

user create

Create a new user account.

Usage:

housectl user create <USERNAME> <PASSWORD> <EMAIL>

Arguments:

<USERNAME> - Unique username for the account
<PASSWORD> - Password (min 8 characters, must include uppercase, lowercase, number, and special character)
<EMAIL> - Email address for the account

Example:

housectl user create alice Secret123! alice@example.com

Password Requirements:

Minimum 8 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character

user get

Retrieve user details by ID or username.

Usage:

housectl user get <USER>

Arguments:

<USER> - User ID (UUID format) or username

Examples:

# Get by username
housectl user get alice

# Get by UUID
housectl user get 550e8400-e29b-41d4-a716-446655440000

user update

Modify user account properties.

Usage:

housectl user update <USER> [OPTIONS]

Arguments:

<USER> - User ID (UUID format) or username

Options:

--username <USERNAME> - New username
--email <EMAIL> - New email address
--active <BOOL> - Set active status (true to enable, false to disable)

Example:

housectl user update alice --email newemail@example.com --active true

user change-password

Change a user's password.

Usage:

housectl user change-password <USER> <PASSWORD>

Arguments:

<USER> - User ID (UUID format) or username
<PASSWORD> - New password (must meet password requirements)

Example:

housectl user change-password alice NewSecret123!

user delete

Permanently delete a user account.

Usage:

housectl user delete <USER> [OPTIONS]

Arguments:

<USER> - User ID (UUID format) or username to delete

Options:

-y, --yes - Skip confirmation prompt (use with caution)

Example:

housectl user delete alice --yes

Warning: This action is irreversible.

tenant

Tenant management and user association commands.

tenant get

Retrieve tenant details by ID or name.

Usage:

housectl tenant get <ID>

Arguments:

<ID> - Tenant ID (UUID) or unique name

Examples:

# Get by name
housectl tenant get acme-corp

# Get by UUID
housectl tenant get 550e8400-e29b-41d4-a716-446655440000

tenant current

Display the tenant associated with your current login session.

Usage:

housectl tenant current

Example:

housectl tenant current

tenant update

Modify tenant properties.

Usage:

housectl tenant update <ID> [OPTIONS]

Arguments:

<ID> - Tenant ID (UUID) or name to update

Options:

--name <NAME> - New display name for the tenant
--description <DESCRIPTION> - New description for the tenant
--subscription <PLAN> - Subscription plan identifier (e.g., 'free', 'pro', 'enterprise')
--active <BOOL> - Set active status (true to enable, false to disable)

Example:

housectl tenant update acme-corp --name "Acme Corporation" --description "Updated description"

tenant delete

Permanently delete a tenant and all associated resources.

Usage:

housectl tenant delete <ID> [OPTIONS]

Arguments:

<ID> - Tenant ID (UUID) or name to delete

Options:

-y, --yes - Skip confirmation prompt (use with extreme caution)

Example:

housectl tenant delete acme-corp --yes

Warning: This action is irreversible and will delete all domains, policies, and user associations.

tenant disable-domain

Disable a specific domain within a tenant.

Usage:

housectl tenant disable-domain <DOMAIN> [OPTIONS]

Arguments:

<DOMAIN> - Domain ID (UUID) or name to disable

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)

Example:

housectl tenant disable-domain billing-domain --tenant acme-corp

tenant associate-user

Grant a user access to a tenant.

Usage:

housectl tenant associate-user <TENANT> <USERNAME>

Arguments:

<TENANT> - Tenant ID (UUID) or name to associate the user with
<USERNAME> - Username to associate

Examples:

# Associate by tenant name
housectl tenant associate-user acme-corp alice@example.com

# Associate by tenant UUID
housectl tenant associate-user 550e8400-e29b-41d4-a716-446655440000 alice@example.com

tenant disassociate-user

Remove a user's access from a tenant.

Usage:

housectl tenant disassociate-user <TENANT> <USERNAME>

Arguments:

<TENANT> - Tenant ID (UUID) or name to remove the user from
<USERNAME> - Username to remove

Examples:

housectl tenant disassociate-user acme-corp alice@example.com
housectl tenant disassociate-user 550e8400-e29b-41d4-a716-446655440000 alice@example.com

tenant is-user-associated

Check if a user is associated with a tenant.

Usage:

housectl tenant is-user-associated <TENANT> <USERNAME>

Arguments:

<TENANT> - Tenant ID (UUID) or name to check
<USERNAME> - Username to check

Examples:

housectl tenant is-user-associated acme-corp alice@example.com
housectl tenant is-user-associated 550e8400-e29b-41d4-a716-446655440000 alice@example.com

tenant all-associated-users

List all users associated with a tenant.

Usage:

housectl tenant all-associated-users [TENANT]

Arguments:

[TENANT] - Tenant ID (UUID) or name (defaults to your current tenant)

Examples:

# List users in current tenant
housectl tenant all-associated-users

# List users in specific tenant by name
housectl tenant all-associated-users acme-corp

# List users in specific tenant by UUID
housectl tenant all-associated-users 550e8400-e29b-41d4-a716-446655440000

tenant service-account create

Create a service account for automated systems and integrations.

Usage:

housectl tenant service-account create <NAME> <DESCRIPTION> [OPTIONS]

Arguments:

<NAME> - Service account name (will be automatically prefixed with 'svc:')
<DESCRIPTION> - Human-readable description of the service account's purpose

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)
--expiration-days <DAYS> - API key expiration period in days (default: 365)

Example:

housectl tenant service-account create billing-webhook "Handles billing webhooks" --expiration-days 90

tenant service-account list

List all service accounts for a tenant.

Usage:

housectl tenant service-account list [OPTIONS]

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)
--active-only - Filter to show only active service accounts

Example:

housectl tenant service-account list --active-only

tenant service-account get

Retrieve details of a specific service account.

Usage:

housectl tenant service-account get <ID>

Arguments:

<ID> - Service account ID (UUID format)

Example:

housectl tenant service-account get 550e8400-e29b-41d4-a716-446655440000

tenant service-account update

Update a service account's status.

Usage:

housectl tenant service-account update <ID> [OPTIONS]

Arguments:

<ID> - Service account ID (UUID format)

Options:

--active <BOOL> - Set active status (true to enable, false to disable)

Example:

housectl tenant service-account update 550e8400-e29b-41d4-a716-446655440000 --active false

tenant service-account delete

Permanently delete a service account and revoke its access.

Usage:

housectl tenant service-account delete <ID> [OPTIONS]

Arguments:

<ID> - Service account ID (UUID format)

Options:

-y, --yes - Skip confirmation prompt (use with caution)

Example:

housectl tenant service-account delete 550e8400-e29b-41d4-a716-446655440000 --yes

Warning: This action is irreversible and will revoke all access for this service account.

admin

System administration commands (requires admin privileges).

admin create

Create a new tenant organization.

Usage:

housectl admin create <NAME> <DESCRIPTION>

Arguments:

<NAME> - Unique name for the tenant organization (≤100 characters)
<DESCRIPTION> - Human-readable description of the tenant (≤500 characters)

Example:

housectl admin create "Acme Corp" "Enterprise customer"

Input Validation:

Tenant name: ≤100 characters, cannot be empty
Description: ≤500 characters, cannot be empty

admin disable

Disable a tenant (suspends all access for that organization).

Usage:

housectl admin disable [TENANT_ID] [OPTIONS]

Arguments:

[TENANT_ID] - Tenant ID (UUID) to disable; defaults to current tenant if omitted

Options:

-y, --yes - Skip confirmation prompt

Example:

housectl admin disable 550e8400-e29b-41d4-a716-446655440000

admin enable

Enable a previously disabled tenant.

Usage:

housectl admin enable [TENANT_ID] [OPTIONS]

Arguments:

[TENANT_ID] - Tenant ID (UUID) to enable; defaults to current tenant if omitted

Options:

-y, --yes - Skip confirmation prompt

Example:

housectl admin enable 550e8400-e29b-41d4-a716-446655440000

admin tenant-set-enabled

Set tenant enabled/disabled status explicitly.

Usage:

housectl admin tenant-set-enabled <STATUS> [TENANT_ID] [OPTIONS]

Arguments:

<STATUS> - Target status: true (enabled) or false (disabled)
[TENANT_ID] - Tenant ID (UUID); defaults to current tenant if omitted

Options:

-y, --yes - Skip confirmation prompt

Example:

housectl admin tenant-set-enabled true 550e8400-e29b-41d4-a716-446655440000

admin list

List tenants or users in the system.

Usage:

housectl admin list tenants
housectl admin list users

Examples:

# List all tenants
housectl admin list tenants

# List all users
housectl admin list users

admin refresh-tenants

Reset API call limit counters for all tenants.

Usage:

housectl admin refresh-tenants

Example:

housectl admin refresh-tenants

Notes:

Use this after changing call limit configurations
Clears accumulated usage counters (resets call quotas to maximum)

domain

Domain management commands (authorization policy containers).

domain create

Create a new authorization domain with policies.

Usage:

housectl domain create <NAME> [TENANT] [POLICIES...]

Arguments:

<NAME> - Unique name for the domain
[TENANT] - Tenant ID or name (defaults to your current tenant)
[POLICIES...] - Policy files or directories to include in the domain

Examples:

# Create domain with single policy file
housectl domain create billing-domain ./policies/billing.toml

# Create domain with policy directory
housectl domain create api-access my-tenant ./policies/

# Create domain with multiple policy files
housectl domain create production-access acme-corp policy1.toml policy2.toml

Notes:

Domains are containers for authorization policies
Define access control rules for resources

domain get

Retrieve domain details by ID or name.

Usage:

housectl domain get <DOMAIN> [OPTIONS]

Arguments:

<DOMAIN> - Domain ID (UUID) or name

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)

Examples:

# Get by name
housectl domain get billing-domain

# Get by UUID with specific tenant
housectl domain get 550e8400-e29b-41d4-a716-446655440000 --tenant acme-corp

domain list

List all domains in a tenant.

Usage:

housectl domain list [OPTIONS]

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)

Examples:

# List domains in current tenant
housectl domain list

# List domains in specific tenant
housectl domain list --tenant acme-corp

domain update

Modify domain properties.

Usage:

housectl domain update <DOMAIN> [OPTIONS]

Arguments:

<DOMAIN> - Domain ID (UUID) or name to update

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)
--name <NAME> - New name for the domain
--active <BOOL> - Set active status (true to enable, false to disable)

Example:

housectl domain update billing-domain --name new-billing-domain --active true

domain delete

Permanently delete a domain and its policies.

Usage:

housectl domain delete <DOMAIN> [OPTIONS]

Arguments:

<DOMAIN> - Domain ID (UUID) or name to delete

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)
-y, --yes - Skip confirmation prompt (use with caution)

Example:

housectl domain delete billing-domain --yes

Warning: This action is irreversible.

domain put-policies

Replace all policies in a domain.

Usage:

housectl domain put-policies <DOMAIN_UUID> <POLICIES...>

Arguments:

<DOMAIN_UUID> - Domain UUID (use housectl domain list to find UUIDs)
<POLICIES...> - Policy files or directories to deploy

Examples:

# Replace with policy directory
housectl domain put-policies 550e8400-e29b-41d4-a716-446655440000 ./policies/

# Replace with specific policy files
housectl domain put-policies 550e8400-e29b-41d4-a716-446655440000 policy1.toml policy2.toml

Notes:

This is an atomic operation
Either all policies are updated or none are

domain list-policies

List all policies in a domain.

Usage:

housectl domain list-policies <DOMAIN> [OPTIONS]

Arguments:

<DOMAIN> - Domain ID (UUID) or name

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)

Examples:

# List policies by domain name
housectl domain list-policies billing-domain

# List policies by domain UUID
housectl domain list-policies 550e8400-e29b-41d4-a716-446655440000

domain get-policy

Get a specific policy from a domain by name.

Usage:

housectl domain get-policy <DOMAIN> <POLICY_NAME> [OPTIONS]

Arguments:

<DOMAIN> - Domain ID (UUID) or name
<POLICY_NAME> - Policy name to retrieve

Options:

--tenant <TENANT> - Tenant ID or name (defaults to your current tenant)

Examples:

housectl domain get-policy billing-domain admin-access
housectl domain get-policy api-domain read-only-policy

authz

Authorization checks and policy management commands.

authz can-i

Check if a request is authorized against server policies.

Usage:

housectl authz can-i <REQUEST_FILE>

Arguments:

<REQUEST_FILE> - Path to JSON file containing the authorization request

Example:

housectl authz can-i request.json

Request File Format (request.json):

{
  "context": {
    "subject": "user:alice",
    "action": "read",
    "object": "hc://domain/550e8400-e29b-41d4-a716-446655440000/documents/doc-123"
  }
}

Response:

Returns ALLOW or DENY

authz can-i-maybe

Test authorization with custom policies (speculative check).

Usage:

housectl authz can-i-maybe <REQUEST> <POLICIES...>

Arguments:

<REQUEST> - Request to check (use 'file://' prefix for file path, or inline JSON)
<POLICIES...> - Policy files or directories to evaluate against (in addition to server policies)

Examples:

# Test with policy directory
housectl authz can-i-maybe request.json ./policies/

# Test with file URI
housectl authz can-i-maybe file://request.json policy1.toml policy2.toml

Notes:

Evaluates request using both server policies and locally-provided test policies
Useful for testing policy changes before deployment

authz can-i-local

Evaluate authorization locally without server connection.

Usage:

housectl authz can-i-local --request <FILE> [OPTIONS] <POLICIES...>

Arguments:

<POLICIES...> - Policy files or directories to evaluate against

Options:

--request <FILE> - Path to JSON file containing the authorization request
--tenant <UUID> - Tenant ID to simulate (equivalent to JWT tenant_id claim)
--domain <DOMAIN> - Domain name or ID to evaluate against

Examples:

# Local evaluation with policy directory
housectl authz can-i-local --request request.json ./policies/

# Local evaluation with tenant context
housectl authz can-i-local --request request.json --tenant 550e8400-e29b-41d4-a716-446655440000 ./policies/

Notes:

Performs authorization evaluation entirely offline
Useful for testing and development without a running server

authz parse-policies

Parse and validate policy files without executing them.

Usage:

housectl authz parse-policies <POLICIES...>

Arguments:

<POLICIES...> - Policy files or directories to validate

Examples:

# Validate policy directory
housectl authz parse-policies ./policies/

# Validate specific policy files
housectl authz parse-policies policy1.toml policy2.toml

Exit Codes:

0 - All policies are valid
1 - One or more policies have errors

Notes:

Validates policy syntax and structure
Useful for CI/CD pipelines and pre-commit hooks

api-key

API key management for programmatic access.

api-key create

Create a new API key for programmatic access.

Usage:

housectl api-key create <USER_ID>

Arguments:

<USER_ID> - User ID (UUID format) to create key for

Example:

housectl api-key create 550e8400-e29b-41d4-a716-446655440000

api-key get

Retrieve details of an existing API key.

Usage:

housectl api-key get <USER_ID> <KEY_ID>

Arguments:

<USER_ID> - User ID (UUID format) who owns the key
<KEY_ID> - API key ID (UUID format) to retrieve

Example:

housectl api-key get 550e8400-e29b-41d4-a716-446655440000 660e8400-e29b-41d4-a716-446655440001

api-key delete

Delete an API key (revokes programmatic access).

Usage:

housectl api-key delete <USER_ID> <KEY_ID> [OPTIONS]

Arguments:

<USER_ID> - User ID (UUID format) who owns the key
<KEY_ID> - API key ID (UUID format) to delete

Options:

-y, --yes - Skip confirmation prompt (use with caution)

Example:

housectl api-key delete 550e8400-e29b-41d4-a716-446655440000 660e8400-e29b-41d4-a716-446655440001 --yes

Error Handling

Exit Codes

Code	Meaning
`0`	Success or operation cancelled
`1`	Generic error
`2`	Invalid input
`3`	Not authenticated
`4`	API error
`5`	Client error
`6`	IO error
`7`	Invalid state

Common Errors

Not Logged In:

Error: NotLoggedInError
Please run: housectl config login

Solution: Run housectl config login <ENDPOINT> <USERNAME> and add --tenant <TENANT> once you need a tenant-scoped session.

Token Expired:

Error: Your token will expire in less than 5 minutes

Solution: housectl automatically attempts to refresh tokens. If this fails, re-login.

Connection Error:

Error: Cannot connect to the server

Solutions:

Check that the server is running
Verify the endpoint URL is correct
Check your network connection

Invalid Configuration:

Error: ConfigurationError

Solution: Check configuration file exists and has correct permissions (chmod 600)

Output Formats

Pretty Format (Default)

Human-readable output with formatting:

housectl user get alice

User: alice
ID: 550e8400-e29b-41d4-a716-446655440000
Email: alice@example.com
Active: true

JSON Format

Machine-parsable output:

housectl user get alice --format json

{
  "username": "alice",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "alice@example.com",
  "active": true
}

Table Format

Tabular output for list commands:

housectl admin list tenants --format table

ID                                   NAME        ACTIVE
550e8400-e29b-41d4-a716-446655440000 acme-corp   true
660e8400-e29b-41d4-a716-446655440001 beta-corp   true

Scripting and Automation

Using JSON Output for Parsing

#!/bin/bash
# Extract user emails
housectl admin list users --format json | jq -r '.users[].email'

Using Environment Variables

#!/bin/bash
# Automated login
export HOUSECARL_PASSWORD=Secret123!
housectl config login https://housecarl.example.com root

Batch Operations

#!/bin/bash
# Create multiple users from CSV

while IFS=, read -r username email password; do
  housectl user create "$username" "$password" "$email"
done < users.csv

Error Handling in Scripts

#!/bin/bash
# Check exit codes

if housectl config health; then
  echo "Server is serving"
else
  echo "Health check failed (exit code: $?)"
  exit 1
fi

Best Practices

Security

Protect configuration files: chmod 600 ~/.config/housecarl.toml
Use strong passwords (min 8 chars, mixed case, numbers, special chars)
Rotate API keys regularly
Don't commit config files to version control
Use environment-specific credentials
Set appropriate token durations for your use case

Operations

Test authorization changes in non-production first
Backup policies before making changes
Use descriptive names for tenants and domains
Document policy decisions
Review audit logs regularly
Use --yes flag only in automated scripts

Development

Use separate tenants for dev/staging/prod
Script repetitive operations
Validate inputs before submission
Handle errors gracefully in scripts
Use authz parse-policies in CI/CD pipelines
Test policies locally before deployment with authz can-i-local

Advanced Usage

Multi-Environment Management

# Login to different environments (each creates a context)
housectl config login https://dev.housecarl.example.com root --as dev-admin
housectl config login https://prod.housecarl.example.com root --as prod-admin

# List all available contexts
housectl config list

# Switch between environments
housectl config use dev-admin
housectl config use prod-admin

# Use environment variable for scripts
HOUSECARL_CONTEXT=prod-admin housectl admin list users

# Use --context flag for one-off commands
housectl --context prod-admin admin list users

Policy Testing Workflow

# 1. Parse policies locally
housectl authz parse-policies ./policies/

# 2. Test locally without server
housectl authz can-i-local --request test-request.json ./policies/

# 3. Test speculatively with server
housectl authz can-i-maybe test-request.json ./policies/

# 4. Deploy to server (use your domain UUID)
housectl domain put-policies <domain-uuid> ./policies/

# 5. Verify with real authorization check
housectl authz can-i test-request.json

Continuous Integration

# Example GitHub Actions workflow
- name: Validate Policies
  run: |
    ./housectl authz parse-policies ./policies/
    if [ $? -ne 0 ]; then
      echo "Policy validation failed"
      exit 1
    fi

Troubleshooting

Cannot Connect to Server

# The gRPC port does not answer plain HTTP curl requests
# Check server health instead
housectl config health

# Verify configuration
housectl config status

# Test an authenticated RPC once you have a tenant-scoped session
housectl config ping

Token Issues

# Check token status
housectl config status

# Re-login to get new token
housectl config login <ENDPOINT> <USERNAME>

Permission Denied

Ensure the authenticated user has appropriate permissions:

Admin operations require admin role
Tenant operations require tenant membership
Some operations are tenant-scoped

Config File Errors

# Check file exists
ls -la ~/.config/housecarl.toml

# Check permissions
chmod 600 ~/.config/housecarl.toml

# List available contexts
housectl config list

# Recreate config with login
rm ~/.config/housecarl.toml
housectl config login <ENDPOINT> <USERNAME>

Context Not Found

If you get a "Context not found" error:

# List available contexts
housectl config list

# Switch to an existing context
housectl config use <context-name>

# Or login again to create a new context
housectl config login <ENDPOINT> <USERNAME>

Support

For issues, bug reports, or feature requests, visit:

GitHub Issues: https://github.com/upside-down-research/code/issues
Documentation: https://authz.housecarl.cloud/docs/