feat: CLI tool for attaching to running JVM processes

[rlaope]

Problem

Currently, Argus must be configured at JVM startup with -javaagent flag:

• Cannot attach to already running applications
• Requires application restart
• Not suitable for production debugging scenarios
• Manual discovery of running Java processes

Proposed Solution

Create a standalone CLI tool that can:

1. List running Java processes
2. Attach Argus agent to a running JVM
3. Provide interactive profiling session
4. Detach cleanly when done

Acceptance Criteria

• Create argus-cli module
• Implement argus list - list Java processes
• Implement argus attach <PID> - attach to process
• Implement argus detach <PID> - detach from process
• Implement argus status - show attached processes
• Support -p <port> for server port
• Create native executable with GraalVM
• Publish to Homebrew

CLI Commands

List Java Processes

$ argus list

PID      NAME                           JAVA VERSION
12345    com.example.MyApp              21.0.1
12346    org.springframework.boot...    21.0.1
12347    com.intellij.idea.Main         17.0.2

Attach to Process

$ argus attach 12345

Attaching to process 12345 (com.example.MyApp)...
✓ Agent loaded successfully
✓ JFR streaming started
✓ WebSocket server started on port 8080

Dashboard: http://localhost:8080/
Press Ctrl+C to detach

Attach with Options

$ argus attach 12345 -p 9090 --no-server --buffer-size 131072

Detach

$ argus detach 12345

Detaching from process 12345...
✓ JFR streaming stopped
✓ Agent unloaded

Status

$ argus status

ATTACHED PROCESSES:
PID      PORT     EVENTS     ACTIVE THREADS
12345    8080     15,234     45

Technical Implementation

Attach API

// Using com.sun.tools.attach
VirtualMachine vm = VirtualMachine.attach(pid);
vm.loadAgent(agentPath, options);

Agent Options

port=8080;buffer=65536;server=true

Native Image (GraalVM)

native-image \
  --no-fallback \
  -H:Name=argus \
  -jar argus-cli.jar

Installation

Homebrew (macOS/Linux)

brew tap rlaope/argus
brew install argus

Manual Download

curl -L https://github.com/rlaope/Argus/releases/latest/download/argus-cli -o argus
chmod +x argus
sudo mv argus /usr/local/bin/

From Source

./gradlew :argus-cli:nativeImage
./argus-cli/build/native/argus

UI Mockup (Terminal)

┌────────────────────────────────────────────────────────────────────┐
│  Argus CLI - Virtual Thread Profiler                               │
├────────────────────────────────────────────────────────────────────┤
│  Attached to: com.example.MyApp (PID: 12345)                       │
│  Dashboard:   http://localhost:8080/                               │
├────────────────────────────────────────────────────────────────────┤
│  Events: 15,234  │  Active: 45  │  Pinned: 3  │  Clients: 1       │
├────────────────────────────────────────────────────────────────────┤
│  Recent Events:                                                    │
│  12:00:01.123  START   VT-1234  (carrier: FJP-1-worker-1)         │
│  12:00:01.124  END     VT-1230  duration: 45ms                     │
│  12:00:01.125  PINNED  VT-1235  synchronized block                 │
│  12:00:01.126  START   VT-1236  (carrier: FJP-1-worker-2)         │
├────────────────────────────────────────────────────────────────────┤
│  Press 'q' to detach, 'd' for thread dump, 'h' for help           │
└────────────────────────────────────────────────────────────────────┘

Technical Considerations

• Requires tools.jar or JDK 9+ attach API
• May require matching JVM versions (attach to JDK 21 from JDK 21)
• Handle permission issues (same user or root)
• Support for containerized JVMs (Docker)
• Windows support via different attach mechanism