CLI Reference

CLI Reference

Complete reference for all LeanJ CLI commands.

Overview

The CLI (leanj) is the heart of the system. All operations go through the CLI.

Commands

Controller Management

Start Controller

Start the controller daemon:

leanj controller start

Options:

• --port <port> - HTTP API port (default: 9877)
• TCP port is HTTP port - 1 (default: 9876)

Environment Variables:

• LEANJ_CONTROLLER_PORT - HTTP port (default: 9877)

Example:

leanj controller start --port 8888

Stop Controller

Stop the running controller:

# Auto-detect PID
leanj controller stop

# Manual PID
leanj controller stop <pid>

JVM Discovery

List JVMs

List all discovered JVMs:

leanj jvms

Options:

• --json - Output in JSON format

Output:

Found 2 JVM(s):

1. com.example.SampleLoop
   ID: abc123
   PID: 12345
   Environment: local

2. order-service
   ID: def456
   Environment: docker
   App: order-service

JSON Output:

leanj jvms --json

[
  {
    "jvmId": "abc123",
    "pid": "12345",
    "appName": "com.example.SampleLoop",
    "environment": "local"
  },
  {
    "jvmId": "def456",
    "appName": "order-service",
    "environment": "docker"
  }
]

Attach/Detach

Attach Agent

Attach the profiler agent to a JVM:

# Using PID
leanj attach --pid <pid>

# Using JVM ID
leanj attach --jvm-id <id>

Example:

leanj attach --pid 12345
leanj attach --jvm-id abc123

Detach Agent

Detach the profiler agent from a JVM:

leanj detach --jvm-id <id>

Example:

leanj detach --jvm-id abc123

Status & Health

Status

Check controller and agent status:

leanj status

Output:

Controller: Running (PID: 12345)
HTTP Port: 9877
TCP Port: 9876

Attached JVMs: 2
- abc123 (PID: 67890)
- def456 (Docker: order-service)

Doctor

Run system health check:

leanj doctor

Checks:

• Java installation
• Go installation
• Controller JAR exists
• Agent JAR exists
• Tools.jar availability
• Controller running status
• Port availability

Output:

✓ Java: Found (11.0.19)
✓ Go: Found (1.21.0)
✓ Controller JAR: Found
✓ Agent JAR: Found
✓ Tools.jar: Found
✓ Controller: Running
✓ Ports: Available (9876, 9877)

License Management

Purchase License

Open license purchase page:

leanj license purchase

Opens Lemon Squeezy checkout in your browser.

Login

Activate Pro license with key:

leanj license login <key>

Example:

leanj license login abc123-def456-ghi789

Status

Check license status:

# Human-readable
leanj license status

# JSON format
leanj license status --json

Output:

License: Pro
Status: Active
Expires: 2025-12-31
Features: All Pro features enabled

Validate

Validate license with backend:

leanj license validate

Note: License validation is cached for 24 hours to reduce API calls.

Info

Get detailed license information:

leanj license info

Shows:

• License tier (Free/Pro)
• Status
• Expiration date
• Features enabled
• Machine ID

Logout

Log out and return to Free tier:

leanj license logout

Environment Variables

Controller Configuration

• LEANJ_CONTROLLER_PORT - HTTP API port (default: 9877)

CLI Configuration

• LEANJ_CLI_PATH - CLI binary path (for IDE)

License Configuration

• LEANJ_LICENSE_API_URL - License API URL (default: Cloudflare Worker)
• LEANJ_MACHINE_ID - Machine ID (auto-generated if not set)
• LEMON_SQUEEZY_CHECKOUT_URL - Checkout URL for purchases
• LEANJ_DEV_MODE - Development mode (test licenses)

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Controller not running
• 3 - JVM not found
• 4 - Attach failed
• 5 - License error

Examples

Complete Workflow

# 1. Start controller
leanj controller start

# 2. Discover JVMs
leanj jvms

# 3. Attach to JVM
leanj attach --pid 12345

# 4. Check status
leanj status

# 5. Detach when done
leanj detach --jvm-id abc123

# 6. Stop controller
leanj controller stop

Docker Workflow

# 1. Start controller
leanj controller start

# 2. List Docker JVMs (auto-registered)
leanj jvms

# 3. Attach to Docker JVM
leanj attach --jvm-id def456

# 4. View metrics in IntelliJ

License Workflow

# 1. Purchase license
leanj license purchase

# 2. Login with key
leanj license login <key>

# 3. Verify status
leanj license status

# 4. Validate (if needed)
leanj license validate

Troubleshooting

Command Not Found

Error: leanj: command not found

Solution:

1. Verify CLI is built: ls dist/cli/leanj*
2. Add to PATH (see Installation Guide)
3. Or use full path: /path/to/leanj <command>

Controller Not Running

Error: Controller not running

Solution:

leanj controller start

JVM Not Found

Error: JVM not found

Solution:

1. List JVMs: leanj jvms
2. Verify PID is correct: jps -l
3. Check JVM is running

Attach Failed

Error: Attach failed

Solution:

1. Run leanj doctor to check system
2. Verify tools.jar is available
3. Check JVM supports attach API
4. Ensure correct PID

Next Steps

• Learn about Configuration
• Read How It Works
• See Troubleshooting Guide