Tracing

All trace commands live under the trace group (alias: t).

valiqor trace <init|apply|uninstrument|refresh>
# or
valiqor t <init|apply|uninstrument|refresh>

trace init

Scan your codebase for LLM usage and generate a valiqor_init.py initialization file with workflow suggestions.

valiqor trace init [flags]

Flag	Type	Default	Description
`--defaults` / `-d`	`flag`	`false`	Use default settings without prompting
`--force` / `-f`	`flag`	`false`	Overwrite existing `valiqor_init.py`
`--no-scan`	`flag`	`false`	Skip codebase scanning (faster, no suggestions)
`--verbose` / `-v`	`flag`	`false`	Show detailed scan output

What It Does

Runs a context scanner for feature detection
Scans your codebase for LLM usage (detects providers and entry points)
Generates valiqor_init.py with recommended workflow decorators
Creates the trace output directory
Updates .gitignore to exclude trace files

Example

# Interactive initialization
valiqor trace init

# Quick setup with defaults, overwriting existing config
valiqor trace init --defaults --force

If no .valiqorrc exists, the CLI auto-configures the project before scanning.

trace apply

Apply @trace_workflow decorators to your Python files based on scan suggestions.

valiqor trace apply [flags]

Flag	Type	Default	Description
`--dry-run`	`flag`	`false`	Preview changes without modifying files
`--all`	`flag`	`false`	Apply to all entry points, including alternatives
`--first`	`flag`	`false`	Apply to the first suggestion per file only
`--verbose` / `-v`	`flag`	`false`	Show detailed output

Behavior

By default, applies decorators only to recommended entry points.
--all includes alternative entry points as well.
Creates backups of modified files before applying changes.
If valiqor_init.py is stale (scan ID mismatch), the CLI re-scans automatically before applying.

Example

# Preview what decorators would be applied
valiqor trace apply --dry-run

# Apply to recommended entry points
valiqor trace apply

# Apply to every detected entry point
valiqor trace apply --all

trace uninstrument

Remove auto-applied Valiqor instrumentation (decorators and imports) from Python files.

valiqor trace uninstrument [files...] [flags]

Flag	Type	Default	Description
`files`	`positional`	all `*.py` files	Specific files to uninstrument
`--dry-run`	`flag`	`false`	Show what would be removed without making changes
`--no-recursive`	`flag`	`false`	Only process the current directory (default: recursive)

Example

# Remove instrumentation from all Python files (recursive)
valiqor trace uninstrument

# Preview removal for specific files
valiqor trace uninstrument app.py utils.py --dry-run

# Process current directory only (no recursion)
valiqor trace uninstrument --no-recursive

Excludes dotfiles and valiqor_init.py by default.

trace refresh

Re-scan the codebase and regenerate valiqor_init.py with updated suggestions.

valiqor trace refresh [flags]

Flag	Type	Default	Description
`--verbose` / `-v`	`flag`	`false`	Show detailed scan output

Example

valiqor trace refresh

Runs the context scanner and LLM detection again, then prompts before overwriting the existing valiqor_init.py.

Getting Started

Commands

trace init

What It Does

Example

trace apply

Behavior

Example

trace uninstrument

Example

trace refresh

Example

​trace init

​What It Does

​Example

​trace apply

​Behavior

​Example

​trace uninstrument

​Example

​trace refresh

​Example

trace init

What It Does

Example

trace apply

Behavior

Example

trace uninstrument

Example

trace refresh

Example