Configuration¶

RAPS CLI supports multiple configuration methods: environment variables, profiles, and .env files. Configuration precedence is: environment variables > active profile > defaults.

Required Environment Variables¶

APS_CLIENT_ID¶

Your APS application Client ID from the APS Developer Portal.

# Windows PowerShell
$env:APS_CLIENT_ID = "your_client_id_here"

# macOS/Linux
export APS_CLIENT_ID="your_client_id_here"

APS_CLIENT_SECRET¶

Your APS application Client Secret from the APS Developer Portal.

# Windows PowerShell
$env:APS_CLIENT_SECRET = "your_client_secret_here"

# macOS/Linux
export APS_CLIENT_SECRET="your_client_secret_here"

Optional Environment Variables¶

APS_CALLBACK_URL¶

Callback URL for 3-legged OAuth. Defaults to http://localhost:8080/callback if not specified.

# Windows PowerShell
$env:APS_CALLBACK_URL = "http://localhost:8080/callback"

# macOS/Linux
export APS_CALLBACK_URL="http://localhost:8080/callback"

APS_DA_NICKNAME¶

Design Automation nickname (required only if using Design Automation features).

# Windows PowerShell
$env:APS_DA_NICKNAME = "your_nickname"

# macOS/Linux
export APS_DA_NICKNAME="your_nickname"

Profile Management (v0.4.0+)¶

Profiles allow you to manage multiple configurations for different environments (development, staging, production).

Creating and Using Profiles¶

# Create a new profile
raps config profile create production

# Set configuration values for the active profile
raps config set client_id "your_production_client_id"
raps config set client_secret "your_production_client_secret"
raps config set base_url "https://developer.api.autodesk.com"

# Switch to a different profile
raps config profile use development

# List all profiles
raps config profile list

# Show current active profile
raps config profile current

# Delete a profile
raps config profile delete old-profile

# Export a profile to file (for backup or sharing)
raps config profile export production --output ./prod-profile.json

# Import a profile from file
raps config profile import ./prod-profile.json --name production-backup

Profile Import/Export¶

Profiles can be exported and imported for backup, sharing, or migration between machines.

Export a Profile:

$ raps config profile export production --output ./profiles/prod.json
✓ Profile 'production' exported to ./profiles/prod.json

Export with Secrets (use with caution):

$ raps config profile export production --include-secrets --output ./prod-secret.json
⚠ WARNING: Exported file contains sensitive credentials!
   Store securely and do not commit to version control.
✓ Profile 'production' exported with secrets

Import a Profile:

$ raps config profile import ./profiles/prod.json
✓ Profile 'production' imported successfully!

# Import with a different name
$ raps config profile import ./profiles/prod.json --name prod-backup
✓ Profile 'prod-backup' imported successfully!

Use Cases: - Backup configuration before changes - Share profiles across team (without secrets) - Migrate configuration to a new machine - Standardize team environments

Profile Storage¶

Profiles are stored in: - Windows: %APPDATA%\raps\profiles.json - macOS: ~/Library/Application Support/raps/profiles.json - Linux: ~/.config/raps/profiles.json

Configuration Precedence¶

When RAPS loads configuration, it uses this order:

CLI flags (highest priority, e.g., --timeout, --concurrency)
Environment variables (e.g., RAPS_TIMEOUT, APS_CLIENT_ID)
Active profile (if set)
Defaults (lowest priority)

This means CLI flags always override environment variables and profile settings, making it easy to override for specific commands. Environment variables override profile settings, which is useful for CI/CD scenarios.

Example: Multi-Environment Setup¶

# Development profile
raps config profile create dev
raps config profile use dev
raps config set client_id "dev_client_id"
raps config set client_secret "dev_secret"

# Production profile
raps config profile create prod
raps config profile use prod
raps config set client_id "prod_client_id"
raps config set client_secret "prod_secret"

# Switch between environments
raps config profile use dev   # Use development credentials
raps config profile use prod # Use production credentials

Using .env File¶

You can create a .env file in your working directory to store credentials:

APS_CLIENT_ID=your_client_id_here
APS_CLIENT_SECRET=your_client_secret_here
APS_CALLBACK_URL=http://localhost:8080/callback
APS_DA_NICKNAME=your_nickname

RAPS will automatically load variables from .env files in the current directory and parent directories.

Security Note: Never commit .env files to version control. Add .env to your .gitignore.

Making Environment Variables Permanent¶

Windows PowerShell¶

Add to your PowerShell profile ($PROFILE):

# Edit profile
notepad $PROFILE

# Add these lines:
$env:APS_CLIENT_ID = "your_client_id_here"
$env:APS_CLIENT_SECRET = "your_client_secret_here"

Windows Command Prompt¶

Use System Properties → Environment Variables, or:

setx APS_CLIENT_ID "your_client_id_here"
setx APS_CLIENT_SECRET "your_client_secret_here"

macOS/Linux¶

Add to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):

# Edit your shell config
nano ~/.bashrc  # or ~/.zshrc

# Add these lines:
export APS_CLIENT_ID="your_client_id_here"
export APS_CLIENT_SECRET="your_client_secret_here"

Then reload your shell:

source ~/.bashrc  # or source ~/.zshrc

Shell Completions¶

RAPS supports auto-completion for bash, zsh, fish, PowerShell, and elvish.

PowerShell¶

# Add to your PowerShell profile ($PROFILE)
raps completions powershell | Out-String | Invoke-Expression

# Or save to a file and source it
raps completions powershell > "$env:USERPROFILE\Documents\PowerShell\raps.ps1"
# Then add to $PROFILE: . "$env:USERPROFILE\Documents\PowerShell\raps.ps1"

Bash¶

# Add to ~/.bashrc
eval "$(raps completions bash)"

# Or save to completions directory
raps completions bash > ~/.local/share/bash-completion/completions/raps

Zsh¶

# Add to ~/.zshrc (before compinit)
eval "$(raps completions zsh)"

# Or save to fpath directory
raps completions zsh > ~/.zfunc/_raps
# Add to ~/.zshrc: fpath=(~/.zfunc $fpath)

Fish¶

# Save to completions directory
raps completions fish > ~/.config/fish/completions/raps.fish

Elvish¶

# Add to ~/.elvish/rc.elv
eval (raps completions elvish | slurp)

Testing Configuration¶

After setting up your credentials, test the configuration:

# Test 2-legged authentication
raps auth test

If successful, you'll see a confirmation message. If not, check:

Environment variables are set correctly
Client ID and Secret are valid
Your APS application is active

Token Storage¶

RAPS securely stores authentication tokens in platform-specific directories:

Windows: %APPDATA%\raps\ or %LOCALAPPDATA%\raps\
macOS: ~/Library/Application Support/raps/
Linux: ~/.local/share/raps/ or $XDG_DATA_HOME/raps/

Tokens are automatically refreshed when they expire. You can clear stored tokens by logging out:

raps auth logout

Performance Tuning¶

Request Timeout¶

Control how long RAPS waits for API responses:

# Set timeout to 60 seconds
raps --timeout 60 translate status $URN

# Default is 120 seconds

Environment Variable:

export RAPS_TIMEOUT=60

Concurrency Limits¶

Control parallel operations for batch commands:

# Run 10 concurrent uploads
raps object upload mybucket ./files/*.dwg --batch --parallel --concurrency 10

# Default is 5 concurrent operations

Environment Variable:

export RAPS_CONCURRENCY=10

Recommended Settings¶

Scenario	Timeout	Concurrency
Normal operations	120s (default)	5 (default)
Large file uploads	300s	3
Slow networks	180s	2
Fast networks, many files	60s	10

Pagination Behavior¶

RAPS automatically handles API pagination for list commands:

Fetches all pages by default
Uses API default page sizes (typically 20-100 items)
Results are aggregated before output

For very large result sets (1000+ items), consider:

# Use filters to reduce results
raps issue list $PROJECT_ID --status open --output json

# Stream results for processing
raps bucket list --output json | jq -c '.[]' | while read item; do
  # Process each item
done

OS Keychain Integration¶

For enhanced security, store tokens in your operating system's credential manager:

# Enable keychain storage
export RAPS_USE_KEYCHAIN=true

# Then authenticate
raps auth login

Supported Platforms:

Platform	Credential Store
Windows	Windows Credential Manager
macOS	Keychain
Linux	Secret Service (GNOME Keyring, KWallet)

Tokens stored in the keychain are: - Encrypted at rest - Protected by OS-level access controls - Not accessible to other processes

Fallback: If keychain is unavailable, RAPS falls back to file-based storage.

Next Steps¶

After configuration: