CLI Commands

The CLI is a standalone tool that works on any running JVM process. You don't need to have started the application with any special flags. You don't need to install an agent. If you can see the process in jps, Argus can diagnose it.

Your First Diagnosis

Let's say you have a Java application that's behaving strangely. Here's how you'd investigate:

# Step 1: Find your application's PID
argus ps

# Step 2: Get an overview of the JVM
argus info 12345

# Step 3: Check GC behavior — is the GC working too hard?
argus gc 12345

# Step 4: Look at memory — is something leaking?
argus heap 12345

# Step 5: Check threads — are there too many? Any deadlocked?
argus threads 12345
argus deadlock 12345

# Step 6: If memory is the issue, find what's consuming it
argus histo 12345

Argus CLI in action — diagnosing a running JVM process

All 67 Commands

Every command follows the same pattern: argus <command> <pid>. All commands support --format=json for scripting and --source=auto|agent|jdk to control the data source.

Category	Commands	What they tell you
Process	`ps`, `info`, `init`	Find and identify JVM processes
Memory	`heap`, `histo`, `heapdump`, `diff`, `nmt`	Heap usage, object distribution, native memory
GC	`gc`, `gcutil`, `gccause`, `gcnew`, `zgc`	GC frequency, pause times, causes, generation stats; ZGC live diagnosis (allocation stalls, soft-max breach, cycle overlap) + trend tracking
Threads	`threads`, `deadlock`, `pool`	Thread states, deadlocks, pool analysis
CPU	`profile`, `jfr`	CPU profiling, flight recording
Classes	`classloader`, `classstat`, `stringtable`, `symboltable`	Class loading, interned strings, symbols
Runtime	`sysprops`, `vmflag`, `vmset`, `vmlog`, `env`, `dynlibs`	Configuration, flags, environment
Advanced	`metaspace`, `compiler`, `finalizer`, `jmx`, `report`, `top`	Metaspace, JIT, finalizers, diagnostics

ZGC Diagnosis

ZGC monitoring in one command. argus zgc <PID> runs a 30-second live JFR capture and returns a HEALTHY/WARNING/UNHEALTHY verdict driven by allocation stalls, SoftMaxHeapSize breach, and cycle overlap — the signals JDK Mission Control surfaces with three GUI clicks, in a one-line CLI.

The command pre-checks the target JVM via JMX to confirm ZGC is the active collector, then captures a JFR profile recording, parses ZGC-specific events, and prints a verdict with concrete tuning recommendations. Use --duration=N to override the default 30-second window (5–120 seconds). Allocation stalls now ship with the top-5 allocator call sites from the same JFR capture, so you see what allocated and who stalled in one shot. Use --save/--diff to track ZGC health across deploys, or --watch for live load tests.

$ argus zgc 12345
ZGC Diagnosis (PID 12345, JDK 21, Generational)
Heap         committed 4.2 GB / soft 4.0 GB / max 5.0 GB
Cycles       12 minor, 2 major (avg interval 2.5s)
Allocation Stalls  ✘ 7 stalls in 30s (max 508.8ms)
Verdict: UNHEALTHY  — allocation stalls + soft-max breach

Recommend:
  • Raise -Xmx (e.g. -Xmx7g)
  • Or raise -XX:SoftMaxHeapSize toward -Xmx
  • Profile allocations: argus profile 12345 --event=alloc

If the JVM is not running ZGC, the command exits with a clear message and suggests argus gc <PID> instead. Requires Java 21+ on the target process.

# Save a healthy baseline before a deploy
$ argus zgc 12345 --save=/tmp/zgc-pre.txt
Saved ZGC baseline to: /tmp/zgc-pre.txt

# After the deploy, see what changed
$ argus zgc 12345 --diff=/tmp/zgc-pre.txt
ZGC Diff (baseline 2026-05-08T12:00:00Z → now 2026-05-08T12:30:00Z, +30 min)
  Heap committed     4.0 GB → 4.5 GB    (+512 MB) ⚠
  Allocation stalls  0     → 7         (NEW) ✘
  Pause Mark End     0.30ms → 0.42ms   (+0.12ms ⚠)

# Or watch live during a load test
$ argus zgc 12345 --watch=10 --interval=60