Command line reference
The paretostack command of version 0.3.11, as printed by paretostack --help. Every command also accepts --help.
usage: paretostack [-h] [-V]
{baseline,profile,tune,verify,verify-store,scout,libs,serve,set-code,analyze,optimize,target,examples,opencv-rules,arch,chat,config,doctor,init,dynamic,plan,run,farm,run-all-versions,search,report,apply,reverify,ci,check-download,license,keys,models}
...
positional arguments:
{baseline,profile,tune,verify,verify-store,scout,libs,serve,set-code,analyze,optimize,target,examples,opencv-rules,arch,chat,config,doctor,init,dynamic,plan,run,farm,run-all-versions,search,report,apply,reverify,ci,check-download,license,keys,models}
baseline build + measure a project's baseline
profile Cartographer: hotspots + bound type + roofline + call graph
tune L0 build/runtime tuner (Bayesian search, persisted to the candidate store)
verify Verifier: check a candidate against a reference under a numeric contract
verify-store re-run stored candidates through the Verifier and set their verify status
scout Library Scout: detect hand-written routines, propose + verify library
substitutions
libs probe which catalog libraries are available/optimized on this target
serve web console: drag & drop a project zip/files for a first-step analysis
set-code set/replace the console access code (stored only as a salted hash in
~/.config/paretostack/auth.json)
analyze static analysis + optimization recommendations for a zip or directory
(nothing is executed)
optimize L1 optimizer (Python, bit-exact): bind lookups, inline tiny pure functions
in loops -> patched COPY + diff (original untouched)
target Target Modeler: measure this host and write targets/<name>.yaml
examples the example projects built into the tool: list them, show one, copy one
into a folder, or run one (examples | examples NAME | examples copy NAME
DIR | examples run NAME --yes)
opencv-rules list the OpenCV functions the optimizer knows (V10: hoisting factories out
of loops, replacing hand-written pixel loops)
arch detect the machine this runs on (OS, architecture, CPU, instruction set,
compilers) and list the processor targets you can pass as --target
chat a chat-style front end (the `pareto` command): slash commands, text plots,
and settings advice from a model if one is connected
config the per-user defaults file (default processor target): show it, or change
it with --set target=NAME / --unset target
doctor check this machine (Linux x86_64 / aarch64) and say what is missing
init write a paretostack.yaml into a project (run recipe, version, accuracy
mode)
dynamic step 2b: RUN the recipe on the real workload and report where the time
goes (executes your command)
plan the plan: what each optimization would change, hot code from the profile
when there is one
run the whole chain: analyze, profile, plan, [AI review], backup, build,
verify (= Automate all steps)
farm the measurement farm: machines a recipe can be measured on (reached over
SSH, key login only)
run-all-versions one change set per engine version V3..V8, and the best one
search the autonomous search (V6+): each transform and runtime setting alone,
then combinations of the winners; prints the Pareto front
report the result of a change set: speed-up, accuracy, what changed
apply take a verified change set: write a patch, export the refactored copy, or
change the project in place
reverify run the verification of an existing change set again (after a noisy run,
or on another machine with --machine)
ci the performance gate for CI: time the current code against
paretostack.baseline.json and fail on a significant slowdown (exit 3)
check-download check a downloaded package BEFORE installing it: the signature of its
SHA256SUMS (with the release key that ships in this package) and the
package's own SHA-256
license the license file of a purchased package: status | install FILE (get the
file from your account page at hpc-labs.ai); checked offline
keys AI keys (optional): status | setup (add a key, asks) | set PROVIDER |
remove PROVIDER | test [PROVIDER]; without any AI model only the AI-
assisted features are limited
models AI backends: which are available (all optional)
options:
-h, --help show this help message and exit
-V, --tool-version the version and build of this installation
paretostack baseline
usage: paretostack baseline [-h] [--lang {cpp,java,python}] [--db DB] [--sessions SESSIONS]
[--runs RUNS] [--warmup WARMUP] [--cpu CPU] [--flag FLAG]
project [args ...]
positional arguments:
project
args program arguments
options:
-h, --help show this help message and exit
--lang {cpp,java,python}
--db DB candidate store (must be on a local filesystem)
--sessions SESSIONS
--runs RUNS
--warmup WARMUP
--cpu CPU pin to this logical CPU (default: highest available; single-core focus,
brief §7.1)
--flag FLAG build/runtime flag (repeatable)
paretostack profile
usage: paretostack profile [-h] [--lang {cpp,java,python}] [--tool TOOL] [--cpu CPU] [--top TOP]
[--out OUT]
project [args ...]
positional arguments:
project
args
options:
-h, --help show this help message and exit
--lang {cpp,java,python}
--tool TOOL force a profiler (perf|gprof|cprofile|jfr)
--cpu CPU
--top TOP
--out OUT
paretostack tune
usage: paretostack tune [-h] [--lang {cpp,java,python}] [--db DB] [--budget BUDGET]
[--screen-runs SCREEN_RUNS] [--final-runs FINAL_RUNS] [--top-k TOP_K]
[--cpu CPU] [--contract CONTRACT]
project [args ...]
positional arguments:
project
args
options:
-h, --help show this help message and exit
--lang {cpp,java,python}
--db DB candidate store (must be on a local filesystem)
--budget BUDGET
--screen-runs SCREEN_RUNS
--final-runs FINAL_RUNS
--top-k TOP_K
--cpu CPU
--contract CONTRACT numeric contract (contracts/*.yaml); enables the Verifier gate
paretostack verify
usage: paretostack verify [-h] --contract CONTRACT [--ref REF] [--lang {cpp,java,python}]
[--flag FLAG] [--level LEVEL] [--cpu CPU] [--no-sanitize]
project
positional arguments:
project candidate project dir
options:
-h, --help show this help message and exit
--contract CONTRACT
--ref REF reference project dir (default: same as project, i.e. config-only
candidate)
--lang {cpp,java,python}
--flag FLAG candidate build/runtime flag (repeatable)
--level LEVEL
--cpu CPU
--no-sanitize
paretostack verify-store
usage: paretostack verify-store [-h] [--db DB] --contract CONTRACT [--cpu CPU]
options:
-h, --help show this help message and exit
--db DB
--contract CONTRACT
--cpu CPU
paretostack scout
usage: paretostack scout [-h] [--lang {cpp,java,python}] [--contract CONTRACT] [--db DB]
[--cpu CPU] [--all-functions] [--no-verify] [--out OUT]
project [args ...]
positional arguments:
project
args
options:
-h, --help show this help message and exit
--lang {cpp,java,python}
--contract CONTRACT numeric contract (default: contracts/<benchmark>.yaml)
--db DB
--cpu CPU
--all-functions scan every function, not only Cartographer hotspots
--no-verify detect/match only (no patching/verification)
--out OUT
paretostack libs
usage: paretostack libs [-h] [--lang {cpp,java,python}]
options:
-h, --help show this help message and exit
--lang {cpp,java,python}
paretostack serve
usage: paretostack serve [-h] [--host HOST] [--port PORT] [--allow-host ALLOW_HOST]
[--analysis-only] [--require-login]
options:
-h, --help show this help message and exit
--host HOST
--port PORT
--allow-host ALLOW_HOST
extra Host header accepted (e.g. a DNS name for the LAN address); a non-
loopback --host is added automatically
--analysis-only nobody may run code or write to a project, not even a client on this
machine (the hosted portal's mode: uploads are only analysed); also
PARETOSTACK_ANALYSIS_ONLY=1
--require-login require the access code set with `paretostack set-code` (needed before
exposing the console beyond the LAN)
paretostack set-code
usage: paretostack set-code [-h] [code]
positional arguments:
code 6-12 digits (omit to be prompted)
options:
-h, --help show this help message and exit
paretostack analyze
usage: paretostack analyze [-h] [--json JSON] source
positional arguments:
source project directory or .zip
options:
-h, --help show this help message and exit
--json JSON also write the JSON report here
paretostack optimize
usage: paretostack optimize [-h] --out OUT [--python PYTHON] [--diff DIFF] [--layout] [--parallel]
project
positional arguments:
project project directory
options:
-h, --help show this help message and exit
--out OUT where to write the optimized copy
--python PYTHON interpreter whose installed libraries are used to verify attribute chains
(default: this one)
--diff DIFF also write the unified diff here
--layout also apply L2 data-layout transforms to C/C++ loop nests: interchange / tiling
/ tiled-ikj matmul (bit-exact; opt-in)
--parallel also parallelize independent loops that call provably pure functions (PAR; opt-
in): Python worker pools, C/C++ OpenMP (build with -fopenmp)
paretostack target
usage: paretostack target [-h] [--cpu CPU] [--out OUT]
options:
-h, --help show this help message and exit
--cpu CPU
--out OUT
paretostack examples
usage: paretostack examples [-h] [--yes] [--json] [rest ...]
positional arguments:
rest NAME, or: copy NAME DIR, or: run NAME
options:
-h, --help show this help message and exit
--yes for `run`: go ahead (it executes the example's program several times, in a copy)
--json
paretostack opencv-rules
usage: paretostack opencv-rules [-h] [--json]
options:
-h, --help show this help message and exit
--json
paretostack arch
usage: paretostack arch [-h] [--list] [--json]
options:
-h, --help show this help message and exit
--list list the processor targets and which of them this machine can run
--json
paretostack chat
usage: paretostack chat [-h] [--model {auto,local,claude,anthropic,openai,none}] [--yes]
[--script SCRIPT]
[project]
positional arguments:
project the project folder (default: here if it has paretostack.yaml, else the
word_filter sample)
options:
-h, --help show this help message and exit
--model {auto,local,claude,anthropic,openai,none}
which model advises: auto = the local one if there is one, none = rules
only; a cloud model sees a short summary after you say yes
--yes do not ask before running the project's command or sending the summary to
a cloud model (for scripts)
--script SCRIPT read the lines to type from this file instead of the keyboard
paretostack config
usage: paretostack config [-h] [--set KEY=VALUE] [--unset KEY] [--json]
options:
-h, --help show this help message and exit
--set KEY=VALUE set a default, for example target=x86_64-v3 (names: native or see `paretostack
arch --list`)
--unset KEY remove a default
--json
paretostack doctor
usage: paretostack doctor [-h] [--json] [--install] [--with-models] [--yes]
options:
-h, --help show this help message and exit
--json
--install list the commands that install what is missing (required and recommended, plus
the local model with --with-models)
--with-models include Ollama and the Qwen model sized for this machine
--yes run the install commands (without it they are only printed)
paretostack init
usage: paretostack init [-h] [--run RUN] [--outputs OUTPUTS] [--force] [--tolerance TOLERANCE]
[path]
positional arguments:
path
options:
-h, --help show this help message and exit
--run RUN the command that runs your code, e.g. 'python3 main.py {out}' ({out} = the
folder where the run writes its outputs)
--outputs OUTPUTS comma-separated globs of the output files to compare (relative to the
output folder)
--force
--tolerance TOLERANCE
allowed absolute difference for numeric outputs (needed for --accuracy
contract runs, e.g. 1e-9)
paretostack dynamic
usage: paretostack dynamic [-h] [--version VERSION] [--accuracy {exact,contract}] [--json]
[--target TARGET] [--cpus CPUS] [--machine MACHINE]
[path]
positional arguments:
path project directory (default: here)
options:
-h, --help show this help message and exit
--version VERSION engine version V1..V10 (default: from paretostack.yaml, else 10)
--accuracy {exact,contract}
exact: output must stay byte-identical; contract: numeric differences
within the declared tolerances are allowed
--json machine-readable output
--target TARGET processor target to tune builds for: native (default: this CPU), or a
named one such as x86_64-v3 or aarch64 (see `paretostack arch --list`);
one this machine cannot run is refused
--cpus CPUS run on these cores only (3, 0-3, 0,2): a lane, so several runs can measure
side by side without sharing cores (also PARETOSTACK_CPUS); thread pools
get that many threads
--machine MACHINE measure on this registered farm machine (see `paretostack farm list`); the
original and the optimized copy are run there, alternately
paretostack plan
usage: paretostack plan [-h] [--version VERSION] [--accuracy {exact,contract}] [--json]
[--target TARGET] [--cpus CPUS] [--machine MACHINE]
[path]
positional arguments:
path project directory (default: here)
options:
-h, --help show this help message and exit
--version VERSION engine version V1..V10 (default: from paretostack.yaml, else 10)
--accuracy {exact,contract}
exact: output must stay byte-identical; contract: numeric differences
within the declared tolerances are allowed
--json machine-readable output
--target TARGET processor target to tune builds for: native (default: this CPU), or a
named one such as x86_64-v3 or aarch64 (see `paretostack arch --list`);
one this machine cannot run is refused
--cpus CPUS run on these cores only (3, 0-3, 0,2): a lane, so several runs can measure
side by side without sharing cores (also PARETOSTACK_CPUS); thread pools
get that many threads
--machine MACHINE measure on this registered farm machine (see `paretostack farm list`); the
original and the optimized copy are run there, alternately
paretostack run
usage: paretostack run [-h] [--version VERSION] [--accuracy {exact,contract}] [--json]
[--target TARGET] [--cpus CPUS] [--machine MACHINE] [--select SELECT]
[--ai AI] [--yes] [--force]
[path]
positional arguments:
path project directory (default: here)
options:
-h, --help show this help message and exit
--version VERSION engine version V1..V10 (default: from paretostack.yaml, else 10)
--accuracy {exact,contract}
exact: output must stay byte-identical; contract: numeric differences
within the declared tolerances are allowed
--json machine-readable output
--target TARGET processor target to tune builds for: native (default: this CPU), or a
named one such as x86_64-v3 or aarch64 (see `paretostack arch --list`);
one this machine cannot run is refused
--cpus CPUS run on these cores only (3, 0-3, 0,2): a lane, so several runs can measure
side by side without sharing cores (also PARETOSTACK_CPUS); thread pools
get that many threads
--machine MACHINE measure on this registered farm machine (see `paretostack farm list`); the
original and the optimized copy are run there, alternately
--select SELECT comma-separated plan item ids (default: what is applicable and hot)
--ai AI none (default), or a comma-separated list of: local, claude, anthropic,
openai, all (cloud models send code excerpts: asked to confirm unless
--yes)
--yes do not ask for confirmations (runs your recipe, calls the chosen models)
--force run even when the program mostly waits and only micro-transforms are
selected
paretostack farm
usage: paretostack farm [-h] {list,add,test,remove,provision} ...
positional arguments:
{list,add,test,remove,provision}
list the registered machines
add register a machine (or replace the entry with the same id)
test reachability and what the machine is: architecture, cores, python,
compiler, GPU
remove forget a machine (nothing is changed on it)
provision say what the machine lacks for typical recipes and the commands that
install it (run only with --yes)
options:
-h, --help show this help message and exit
paretostack run-all-versions
usage: paretostack run-all-versions [-h] [--version VERSION] [--accuracy {exact,contract}]
[--json] [--target TARGET] [--cpus CPUS] [--machine MACHINE]
[--select SELECT] [--ai AI] [--yes] [--force]
[path]
positional arguments:
path project directory (default: here)
options:
-h, --help show this help message and exit
--version VERSION engine version V1..V10 (default: from paretostack.yaml, else 10)
--accuracy {exact,contract}
exact: output must stay byte-identical; contract: numeric differences
within the declared tolerances are allowed
--json machine-readable output
--target TARGET processor target to tune builds for: native (default: this CPU), or a
named one such as x86_64-v3 or aarch64 (see `paretostack arch --list`);
one this machine cannot run is refused
--cpus CPUS run on these cores only (3, 0-3, 0,2): a lane, so several runs can measure
side by side without sharing cores (also PARETOSTACK_CPUS); thread pools
get that many threads
--machine MACHINE measure on this registered farm machine (see `paretostack farm list`); the
original and the optimized copy are run there, alternately
--select SELECT comma-separated plan item ids (default: what is applicable and hot)
--ai AI none (default), or a comma-separated list of: local, claude, anthropic,
openai, all (cloud models send code excerpts: asked to confirm unless
--yes)
--yes do not ask for confirmations (runs your recipe, calls the chosen models)
--force run even when the program mostly waits and only micro-transforms are
selected
paretostack search
usage: paretostack search [-h] [--version VERSION] [--accuracy {exact,contract}] [--json]
[--target TARGET] [--cpus CPUS] [--machine MACHINE] [--select SELECT]
[--ai AI] [--yes] [--force] [--budget BUDGET] [--minutes MINUTES]
[--min-accuracy MIN_ACCURACY] [--builds] [--no-build-sandbox]
[--build-network]
[path]
positional arguments:
path project directory (default: here)
options:
-h, --help show this help message and exit
--version VERSION engine version V1..V10 (default: from paretostack.yaml, else 10)
--accuracy {exact,contract}
exact: output must stay byte-identical; contract: numeric differences
within the declared tolerances are allowed
--json machine-readable output
--target TARGET processor target to tune builds for: native (default: this CPU), or a
named one such as x86_64-v3 or aarch64 (see `paretostack arch --list`);
one this machine cannot run is refused
--cpus CPUS run on these cores only (3, 0-3, 0,2): a lane, so several runs can measure
side by side without sharing cores (also PARETOSTACK_CPUS); thread pools
get that many threads
--machine MACHINE measure on this registered farm machine (see `paretostack farm list`); the
original and the optimized copy are run there, alternately
--select SELECT comma-separated plan item ids (default: what is applicable and hot)
--ai AI none (default), or a comma-separated list of: local, claude, anthropic,
openai, all (cloud models send code excerpts: asked to confirm unless
--yes)
--yes do not ask for confirmations (runs your recipe, calls the chosen models)
--force run even when the program mostly waits and only micro-transforms are
selected
--budget BUDGET maximum number of candidates (default 12)
--minutes MINUTES maximum minutes (default 30)
--min-accuracy MIN_ACCURACY
accuracy budget (0..1): a candidate or combination whose accuracy score
(e.g. 1-max_rel) is below this is reported but never combined
--builds V8: also try builds of the project with other compiler / link settings
(slow: each is a full build)
--no-build-sandbox with --builds: run the builds directly on this machine, not in the sandbox
(OpenCV and other big projects download or write outside a sandbox; the
sandbox only exists where podman is installed)
--build-network with --builds: let the builds use the network (dependency downloads)
paretostack report
usage: paretostack report [-h] [--changeset CHANGESET] [--json] [path]
positional arguments:
path
options:
-h, --help show this help message and exit
--changeset CHANGESET
change set id (prefix); default: the newest one
--json
paretostack apply
usage: paretostack apply [-h] [--changeset CHANGESET]
(--patch PATCH | --export EXPORT | --in-place)
[path]
positional arguments:
path
options:
-h, --help show this help message and exit
--changeset CHANGESET
change set id (prefix); default: the newest verified one
--patch PATCH write the patch to this file (the project is not touched)
--export EXPORT copy the refactored tree to this folder (the project is not touched)
--in-place copy the changed files over the project (a backup is kept; nothing is
committed)
paretostack reverify
usage: paretostack reverify [-h] [--version VERSION] [--accuracy {exact,contract}] [--json]
[--target TARGET] [--cpus CPUS] [--machine MACHINE]
[--changeset CHANGESET] [--yes]
[path]
positional arguments:
path project directory (default: here)
options:
-h, --help show this help message and exit
--version VERSION engine version V1..V10 (default: from paretostack.yaml, else 10)
--accuracy {exact,contract}
exact: output must stay byte-identical; contract: numeric differences
within the declared tolerances are allowed
--json machine-readable output
--target TARGET processor target to tune builds for: native (default: this CPU), or a
named one such as x86_64-v3 or aarch64 (see `paretostack arch --list`);
one this machine cannot run is refused
--cpus CPUS run on these cores only (3, 0-3, 0,2): a lane, so several runs can measure
side by side without sharing cores (also PARETOSTACK_CPUS); thread pools
get that many threads
--machine MACHINE measure on this registered farm machine (see `paretostack farm list`); the
original and the optimized copy are run there, alternately
--changeset CHANGESET
change set id (prefix); default: the newest one
--yes do not ask before running your command
paretostack ci
usage: paretostack ci [-h] [--max-regression MAX_REGRESSION] [--update-baseline]
[--ignore-machine] [--optimize] [--version VERSION]
[--accuracy {exact,contract}] [--target TARGET] [--machine MACHINE]
[--report REPORT] [--init-github] [--json] [--yes]
[path]
positional arguments:
path
options:
-h, --help show this help message and exit
--max-regression MAX_REGRESSION
percent slower than the baseline that fails the gate when the slowdown is
also statistically significant (default 5)
--update-baseline (re)write paretostack.baseline.json from this machine's timings (commit
it)
--ignore-machine compare even when the baseline was measured on another kind of machine
--optimize also run the optimizer and put what it finds (verified speed-up, patch) in
the report
--version VERSION
--accuracy {exact,contract}
--target TARGET processor target for builds (native by default; see `paretostack arch
--list`)
--machine MACHINE measure on this registered farm machine
--report REPORT write a Markdown report here (for example $GITHUB_STEP_SUMMARY)
--init-github write .github/workflows/paretostack.yml and exit
--json
--yes do not ask before running your command
paretostack check-download
usage: paretostack check-download [-h] [--sums SUMS] [--sig SIG] [--key KEY] archive
positional arguments:
archive the downloaded .zip / .tar.gz
options:
-h, --help show this help message and exit
--sums SUMS the release's SHA256SUMS (default: the one next to the archive)
--sig SIG its signature (default: SHA256SUMS.sig next to it)
--key KEY the public release key (default: the one inside this package)
paretostack license
usage: paretostack license [-h] [--json] [{status,install}] [file]
positional arguments:
{status,install}
file for install: the license.json you downloaded
options:
-h, --help show this help message and exit
--json
paretostack keys
usage: paretostack keys [-h] [--from-env] [--stdin] [--json]
[{status,setup,set,remove,test}] [{anthropic,openai}]
positional arguments:
{status,setup,set,remove,test}
{anthropic,openai} for set / remove / test
options:
-h, --help show this help message and exit
--from-env for `set`: take the key from ANTHROPIC_API_KEY / OPENAI_API_KEY instead of
asking
--stdin for `set`: read the key from standard input (scripts)
--json
paretostack models
usage: paretostack models [-h] [--yes] [--json] [{list,test,offline}] [backend]
positional arguments:
{list,test,offline}
backend for `test`: local, claude or openai: sends ONE tiny prompt (no project
code) and reports the answer, time and cost; for `offline`: on, off or
status
options:
-h, --help show this help message and exit
--yes for `offline on`: download the recommended model without asking
--json