Agent configuration reference
Find every source-supported startup option, its default and the consequence of enabling it.
Agent argument syntax
java "-javaagent:/absolute/tools/reclazz-agent-X.Y.Z.jar=watchDirs=/absolute/app/target/classes,verbose=true" -jar app.jarUse comma-separated key=value pairs after the agent JAR’s equals sign. Lists use semicolons where documented. Quote the complete agent argument when paths contain spaces. The parser splits commas only where a known key follows; avoid appending unknown keys to another value.
These are application-JVM startup options. Match them to the installed agent version. The full table below is generated from the canonical usage guide in this documentation build; no new runtime dependency is introduced by the docs.
Startup options
| Option | Default | Behavior and scope |
|---|---|---|
hybrisHome | auto-detect | Absolute path to the hybris/ directory |
watchExtensions | all custom | Semicolon-separated extension names to watch (empty = all) |
excludePatterns | (none) | Semicolon-separated glob patterns to exclude (e.g., *Test.class;*Mock*) |
autoCompile | false | Compile .java files internally instead of watching .class files |
autoImpex | false | Auto-import changed .impex files |
debounceMs | 500 | Milliseconds to wait before processing changes (batches rapid file writes) |
startupDelaySec | 30 | Seconds to wait after agent startup before watching files |
verbose | false | Enable verbose logging in the console, including each framework step's own line after a reload (the reload line carries the summary either way) |
statusPort | 0 | TCP port for plugin communication (0 = auto-assign) |
portFile | (none) | Path where agent writes its actual port after binding |
watchDirs | auto-detect | Semicolon-separated class output directories to watch, for a project the detection does not know |
excludeClasses | (none) | Semicolon-separated class name patterns the transform leaves alone; the way out when instrumenting one class is the problem |
impexAllowRemove | false | Let auto-imported ImpEx files run REMOVE lines |
autoUpdateRunningSystem | false | After an items.xml change regenerates the models, run the schema-only Update Running System (add columns, no data, never drop) so a new attribute is live without a manual HAC click. A saved *-locales_<iso>.properties also writes the type, attribute and enumeration names it keys onto the types, as "Localize types" would for those keys only. Writes to the live database, so opt-in and dev-only |
jpaRefresh | false | Opt-in mapping rebuild. Existing fields require enhanced redefinition; new entities also work on stock JDKs, including supported Hibernate validate with a prepared schema. See scope |
structuralReload | true | The companion engine that adds and removes members on a stock JDK; false leaves method-body reloads only |
platform | auto | Skip detection and name the platform (hybris, spring, generic) |
wrapOutput | auto | Wrap console lines to the terminal width: auto, true, false |
transformDumpDir | (none) | Write every transformed class file here, for looking at what the agent emitted |
verifyTransform | false | Run the bytecode verifier over every transformed class and print what it says |
sessionLog | (none) | Append every status line to this file with an ISO timestamp and level, no colour: the session's record, to read back or attach to a report |
reloadBoundary | immediate | request waits for synchronous MVC dispatches and supported Spring 5 javax and Spring 6 Jakarta MVC async requests before applying a class reload batch; requires -javaagent at JVM startup. See Reload between requests |
refreshOwnersOnHelper | (none) | Opt-in helperFqn>owner1;owner2\|helper2>owner3: after a helper class reloads, recreate the named Spring singleton cache-owner beans so a custom cache they hold is rebuilt through the fresh helper logic. Owners are recreated through the normal guarded bean-reload lifecycle; non-singletons, FactoryBeans and event-listener owners are declined. See Refreshing a custom cache after a helper reload |
Defaults keep consequential actions explicit
Source defaults leave automatic ImpEx import, REMOVE permission, schema updating and JPA mapping refresh disabled. Opting into one does not opt into the others. Read its guide and verify its exact supported lifecycle before enabling it.
reloadBoundary=request needs startup attachment and a supported MVC hook. refreshOwnersOnHelper recreates eligible named owners; it does not preserve their instance state.
Sources & version scope
Documentation source 1.4.0 · evidence baseline 75535bd · reviewed 19 October 2026. Check your installed artifact; source features may postdate a release.