Environment Variables

Overview

ntcli uses environment variables to configure various aspects of its behavior, from API endpoints to authentication settings. Most variables have sensible defaults and are managed automatically.

Authentication Variables

OAuth Configuration (Optional)

These variables are automatically configured for the production environment and rarely need to be modified:

CLERK_OAUTH_CLIENT_ID

string

Clerk OAuth client ID for authenticationDefault: Automatically configured for production
When to modify: Custom Clerk environment only (advanced use cases)

CLERK_DOMAIN

string

Clerk domain for OAuth authenticationDefault: Automatically configured for production
When to modify: Custom Clerk environment only (advanced use cases)

API Configuration

Dual-Domain Architecture

NimbleTools uses a dual-domain architecture separating management operations from MCP runtime operations:

NTCLI_MANAGEMENT_API_URL

string

Management API endpoint for workspaces, tokens, secrets, and server managementDefault: https://api.nimbletools.dev
Purpose: Workspace operations, token management, server deployment

NTCLI_MCP_API_URL

string

MCP Runtime endpoint for MCP protocol operationsDefault: https://mcp.nimbletools.dev
Purpose: MCP tool calls, server communication

NTCLI_DEFAULT_PORT

number

Default port for OAuth callback serverDefault: 41247
Range: 1024-65535 (unprivileged ports)

Debug and Development

NTCLI_DEBUG

boolean

Enable detailed HTTP debugging outputDefault: false
Values: 1, true, yes (to enable)

NODE_ENV

string

Node.js environment settingDefault: production
Values: development, staging, production

NODE_TLS_REJECT_UNAUTHORIZED

string

Disable TLS certificate validation (development only)Default: 1 (enabled)
Values: 0 (disable validation), 1 (enable validation)
Use case: Local development with self-signed certificates

Usage Examples

Development Environment

Set up ntcli for local development:

# Development API endpoints
export NTCLI_MANAGEMENT_API_URL=https://dev-api.nimbletools.dev
export NTCLI_MCP_API_URL=https://dev-mcp.nimbletools.dev

# Enable debug output
export NTCLI_DEBUG=1

# Use alternative callback port
export NTCLI_DEFAULT_PORT=3000

# Development environment
export NODE_ENV=development

# Disable TLS validation for self-signed certificates (development only)
export NODE_TLS_REJECT_UNAUTHORIZED=0

CI/CD Environment

Configure ntcli for automated deployments:

# Production API endpoints (defaults)
export NTCLI_MANAGEMENT_API_URL=https://api.nimbletools.dev
export NTCLI_MCP_API_URL=https://mcp.nimbletools.dev

# Disable debug output (default)
export NTCLI_DEBUG=0

# Production environment
export NODE_ENV=production

# Use standard callback port (default)
export NTCLI_DEFAULT_PORT=41247

Corporate/Enterprise

Configure for enterprise deployments:

# Custom enterprise endpoints
export NTCLI_MANAGEMENT_API_URL=https://ntcli-api.company.com
export NTCLI_MCP_API_URL=https://ntcli-mcp.company.com

# Custom OAuth settings (if needed)
export CLERK_DOMAIN=company-auth.clerk.accounts.dev
export CLERK_OAUTH_CLIENT_ID=custom_client_id

# Corporate callback port
export NTCLI_DEFAULT_PORT=8080

Setting Environment Variables

Temporary (Current Session)

export NTCLI_MANAGEMENT_API_URL=https://dev-api.nimbletools.dev
export NTCLI_MCP_API_URL=https://dev-mcp.nimbletools.dev
export NTCLI_DEBUG=1
ntcli auth login

Persistent (Shell Profile)

Add to ~/.bashrc or ~/.bash_profile:

# NimbleTools CLI Configuration
export NTCLI_MANAGEMENT_API_URL=https://api.nimbletools.dev
export NTCLI_MCP_API_URL=https://mcp.nimbletools.dev
export NTCLI_DEFAULT_PORT=41247

Using .env Files

Create a .env file in your project directory:

# .env file
NTCLI_MANAGEMENT_API_URL=https://api.nimbletools.dev
NTCLI_MCP_API_URL=https://mcp.nimbletools.dev
NTCLI_DEBUG=0
NTCLI_DEFAULT_PORT=41247
NODE_ENV=production

Then load it before running ntcli:

# Load .env file and run command
export $(cat .env | xargs) && ntcli auth login

Environment Variable Precedence

Variables are resolved in the following order (highest to lowest priority):

Command-line flags (e.g., --port 3000)
Environment variables (e.g., NTCLI_DEFAULT_PORT=3000)
Configuration files (future feature)
Built-in defaults

Example Priority Resolution

# Environment variable sets default
export NTCLI_DEFAULT_PORT=8080

# Command-line flag overrides environment variable
ntcli auth login --port 3000
# Uses port 3000, not 8080

Debug Output Control

Enable Debug Mode

export NTCLI_DEBUG=1
ntcli auth login --verbose

Debug mode shows:

HTTP request/response details
Authentication flow steps
API endpoint resolutions
Token exchange information
Error stack traces

Debug Output Example

$ NTCLI_DEBUG=1 ntcli auth login
[DEBUG] Starting OAuth flow...
[DEBUG] Callback server starting on port 41247
[DEBUG] Opening browser to: https://clerk.nimbletools.ai/oauth/authorize?...
[DEBUG] Received callback with code: abc123...
[DEBUG] Exchanging code for tokens...
[DEBUG] Authentication successful

Validation and Troubleshooting

Check Current Configuration

# View all environment variables
env | grep NTCLI

# Check specific variables
echo $NTCLI_MANAGEMENT_API_URL
echo $NTCLI_MCP_API_URL
echo $NTCLI_DEFAULT_PORT
echo $NTCLI_DEBUG

Test Configuration

# Test API connectivity
ntcli health

# Test authentication with debug
NTCLI_DEBUG=1 ntcli auth status

# Test with custom endpoints
NTCLI_MANAGEMENT_API_URL=https://dev-api.nimbletools.dev ntcli health

Common Issues

API endpoint not reachable

Symptoms: Connection timeout, DNS resolution errorsCheck:

echo $NTCLI_MANAGEMENT_API_URL
echo $NTCLI_MCP_API_URL
curl -I $NTCLI_MANAGEMENT_API_URL/health

Solution: Verify the API URLs are correct and accessible

OAuth callback port in use

Symptoms: “Port already in use” error during loginCheck:

echo $NTCLI_DEFAULT_PORT
lsof -i :$NTCLI_DEFAULT_PORT  # Check if port is used

Solution: Use a different port or stop the conflicting process

Authentication failures

Security Considerations

Sensitive Variables

Some environment variables contain sensitive information:

Variable	Sensitivity	Recommendation
`CLERK_OAUTH_CLIENT_ID`	Medium	Don’t share publicly
`CLERK_DOMAIN`	Low	Safe to share
`NTCLI_MANAGEMENT_API_URL`	Low	Safe to share
`NTCLI_MCP_API_URL`	Low	Safe to share
`NTCLI_DEBUG`	Low	Disable in production

Best Practices

Development

Use separate OAuth clients and API endpoints for development

Production

Disable debug mode and use production OAuth settings

CI/CD

Store sensitive variables in secure CI/CD secret management

Teams

Document environment setup in team onboarding guides

Authentication Setup

Configure OAuth and authentication settings

Troubleshooting

Common configuration and environment issues

CI/CD Guide

Configure ntcli for automated deployments

Auth Commands

Authentication command reference

Get Started

Core Concepts

Configuration

Overview

Authentication Variables

OAuth Configuration (Optional)

API Configuration

Dual-Domain Architecture

Debug and Development

Usage Examples

Development Environment

CI/CD Environment

Corporate/Enterprise

Setting Environment Variables

Temporary (Current Session)

Persistent (Shell Profile)

Using .env Files

Environment Variable Precedence

Example Priority Resolution

Debug Output Control

Enable Debug Mode

Debug Output Example

Validation and Troubleshooting

Check Current Configuration

Test Configuration

Common Issues

Security Considerations

Sensitive Variables

Best Practices

Development

Production

CI/CD

Teams

Authentication Setup

Troubleshooting

CI/CD Guide

Auth Commands

Get Started

Core Concepts

Configuration

​Overview

​Authentication Variables

​OAuth Configuration (Optional)

​API Configuration

​Dual-Domain Architecture

​Debug and Development

​Usage Examples

​Development Environment

​CI/CD Environment

​Corporate/Enterprise

​Setting Environment Variables

​Temporary (Current Session)

​Persistent (Shell Profile)

​Using .env Files

​Environment Variable Precedence

​Example Priority Resolution

​Debug Output Control

​Enable Debug Mode

​Debug Output Example

​Validation and Troubleshooting

​Check Current Configuration

​Test Configuration

​Common Issues

​Security Considerations

​Sensitive Variables

​Best Practices

Development

Production

CI/CD

Teams

​Related Configuration

Authentication Setup

Troubleshooting

CI/CD Guide

Auth Commands

Overview

Authentication Variables

OAuth Configuration (Optional)

API Configuration

Dual-Domain Architecture

Debug and Development

Usage Examples

Development Environment

CI/CD Environment

Corporate/Enterprise

Setting Environment Variables

Temporary (Current Session)

Persistent (Shell Profile)

Using .env Files

Environment Variable Precedence

Example Priority Resolution

Debug Output Control

Enable Debug Mode

Debug Output Example

Validation and Troubleshooting

Check Current Configuration

Test Configuration

Common Issues

Security Considerations

Sensitive Variables

Best Practices

Related Configuration