Client CLI Guide

Client CLI Guide

Back to Home

Scope

This page explains how to run CoreTrace from the terminal with the current implementation behavior.

Quickstart (Build + Help)

cd /Users/hugopayet/Desktop/CLaude/coretrace
mkdir -p build && cd build
cmake .. -DPARSER_TYPE=CLI11 -DUSE_THREAD_SANITIZER=OFF -DUSE_ADDRESS_SANITIZER=OFF
make -j4
./ctrace --help

Common Workflows

1) Static analysis on explicit files

./ctrace --input ../tests/buffer_overflow.cc --static --verbose

2) Specific tools only

./ctrace --input ../tests/buffer_overflow.cc --invoke tscancode,flawfinder

3) Stack analyzer via tool config

./ctrace --tool-config ../config/tool-config.json --static

4) Start HTTP server mode

./ctrace --ipc serve --serve-host 127.0.0.1 --serve-port 8080 --shutdown-token mytoken

Option Reference (Current Behavior)

Analysis selection

• --static: run the static tool group.
• --dyn: run the dynamic tool group.
• --invoke <csv>: run specific tools.
  • CLI-recognized values in parser logic: flawfinder, ikos, cppcheck, tscancode, ctrace_stack_analyzer.

Input and source resolution

• --input <csv>: direct file list.
• --compile-commands <path>: used for file auto-resolution when no --input is provided.
• --include-compdb-deps: when auto-loading from compile commands, include entries under _deps paths.

Stack analyzer configuration

• --analysis-profile <fast|full>
• --smt <on|off>
• --smt-backend <name>
• --smt-secondary-backend <name>
• --smt-mode <single|portfolio|cross-check|dual-consensus>
• --smt-timeout-ms <n>
• --smt-budget-nodes <n>
• --smt-rules <csv>
• --resource-model <path>
• --escape-model <path>
• --buffer-model <path>
• --stack-limit <bytes>
• --demangle

Runtime and output behavior

• --verbose: enables debug-level logger output.
• --quiet: set in global config; consumed by stack analyzer args.
• --sarif-format: enables SARIF behavior in supported tools.
• --report-file <path>
• --async: enables parallel scheduling through the internal thread pool.
• --ipc <standardIO|socket|serve>
• --ipc-path <path>
• --serve-host <host>
• --serve-port <port>
• --shutdown-token <token>
• --shutdown-timeout-ms <ms>

--tool-config JSON Usage

CoreTrace can preload analysis settings from a JSON file.

Example:

./ctrace --tool-config ../config/tool-config.json --static

tool-config currently supports:

• root invoke (string or array)
• root input (string or array)
• stack_analyzer section (or tools.ctrace_stack_analyzer) for:
  • compile_commands, resource_model, escape_model, buffer_model
  • demangle, timing, include_compdb_deps, quiet
  • stack_limit
  • analysis-profile / analysis_profile
  • smt, smt-backend / smt_backend, smt-secondary-backend / smt_secondary_backend, smt-mode / smt_mode
  • smt-timeout-ms / smt_timeout_ms
  • smt-budget-nodes / smt_budget_nodes
  • smt-rules / smt_rules
  • entry_points

Source File Resolution Rules

CoreTrace resolves inputs in this order:

1. Start from --input file entries.
2. If no --input and --compile-commands is set:
   • if path is a directory, append compile_commands.json
   • if resulting file exists, use it as an input manifest
3. For .json inputs, parse and expand:
   • array of strings
   • array of objects with file, src_file, or path (optional directory base)
   • object with files, sources, or compile_commands arrays
   • object with single file, src_file, or path
4. Resolve relative paths against manifest directory (or per-entry directory when provided).
5. Normalize paths and deduplicate.
6. If the input is an auto-discovered compile commands manifest and --include-compdb-deps is not set, entries containing _deps path segment are filtered out.

If resolution yields no source files, analysis exits with an error.

Server Mode Entry Command

./ctrace --ipc serve --serve-host 127.0.0.1 --serve-port 8080 --shutdown-token mytoken --shutdown-timeout-ms 5000

In server mode, analysis requests are handled over HTTP (/api). See Client HTTP API Reference.

Current Limitations (Reproducible)

• Help text mentions --output-file, but parser registers --output; --output-file is rejected by CLI parser.
• --output is parsed but currently not applied to analysis behavior.
• Help text does not list --serve-host and --serve-port, even though they are supported.
• CLI --invoke silently ignores unknown tool names (only known names are inserted by parser logic).
• cppcheck implementation uses a hardcoded executable path (/opt/homebrew/bin/cppcheck) and its name() currently returns "ikos".
• Static tool availability and execution paths are environment-dependent (flawfinder, tscancode, ikos, cppcheck must be installed/resolvable as expected by the current process launch paths).

Back to Home