jrn — CLI wrapper for Joern

TypeScript CLI that wraps Joern code analysis server via its HTTP API. Command names mirror Joern's native API. Designed for AI-assisted code analysis workflows.

Requirements

• Node.js >= 18
• Joern installed and accessible in PATH

Installation

npm install
npm run build
npm link          # makes `jrn` available globally

Quick Start

# 1. Start Joern server
jrn server start

# 2. Import source code (creates CPG)
jrn importCode ./my-project

# 3. Query the Code Property Graph
jrn query 'cpg.method.name.l'

# 4. Stop server when done
jrn server stop

Commands

Server Lifecycle

jrn server start [--port 8080] [--memory 8G]   # Start Joern server
jrn server stop                                  # Stop server
jrn server status                                # Show running state

Importing Code

# Import source code → creates CPG automatically
jrn importCode ./src --language java

# Import pre-built CPG file (.cpg, .odb, .bin)
jrn importCpg ./workspace/project.cpg

Workspace Management

jrn workspace              # List loaded CPGs/projects
jrn open my-project        # Switch to a named workspace
jrn close                  # Close current CPG
jrn run ossdataflow        # Run overlay pass (e.g. data flow)

Querying

# Arbitrary CPGQL query
jrn query 'cpg.method.name.l'

# Pipe from stdin
echo 'cpg.call.name("gets").callIn.l' | jrn query

# JSON output for AI tools
jrn query --json 'cpg.typeDecl.name.l'

# Raw output
jrn query --raw 'cpg.metaData.l'

# Custom timeout (ms)
jrn query --timeout 60000 'cpg.method.l'

Script Execution

# Execute a Joern script (.sc file)
jrn script analysis.sc

# With parameters
jrn script analysis.sc --params cpgPath=project.cpg maxDepth=5

Global Options

Flag	Description
--json	All output as JSON (for AI/tool integration)
-V, --version	Show version
-h, --help	Show help

Configuration

Per-project: .jrn.json

{
  "port": 8081,
  "jvmMemory": "8G",
  "timeout": 600,
  "autoStart": true
}

Global: ~/.config/jrn/config.json

{
  "joernPath": "/home/user/bin/joern/joern-cli/joern",
  "host": "127.0.0.1",
  "port": 8080,
  "jvmMemory": "4G",
  "timeout": 300,
  "autoStart": false
}

Key	Default	Description
joernPath	"joern"	Path to Joern binary
host	"127.0.0.1"	Server bind host
port	8080	Server port
jvmMemory	"4G"	JVM heap size
timeout	300	Query timeout (seconds)
autoStart	false	Auto-start server on first command

Project .jrn.json overrides global config.

JSON Output Mode

When --json is passed, all commands emit structured JSON to stdout, human-readable messages go to stderr. This makes jrn suitable as a tool for AI assistants:

$ jrn --json query 'cpg.method.name.l.size'
{"success":true,"stdout":"42","stderr":"","timing":150}

$ jrn --json server status
{"running":true,"state":{"pid":12345,"port":8080,"startedAt":"..."},"alive":true}

Architecture

jrn CLI  →  HTTP REST  →  Joern Server (joern --server)
                              ↕
                          JVM + CPG in-memory

• Transport: HTTP REST via Joern's /query-sync endpoint
• Process management: Background joern --server process with PID file at ~/.local/state/jrn/server.json
• No JVM restart overhead: Server stays running, queries execute instantly

Development

npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests

See Also

• CPGQL Query Guide — Complete query reference with examples
• Joern Documentation
• CPGQL Reference Card