Skip to content

Command Line Interface (CLI) Reference 💻

This section documents the subcommands and command-line execution helper modules in dv-agentic-system.

Agent Invocation Commands

These CLI handlers map command-line arguments to agent runs.

Orchestrator Command

orchestrator

CLI entrypoint for OrchestratorAgent.

Sub-agents are wired up automatically based on --simulator and --adapter flags. The LLM client is selected from environment variables (see :mod:~dv_agentic.cli._factory).

When --project-config is provided, the three-layer configuration system is activated: team profile, IP-type rules, and adapter settings are all loaded from .agent/project.yaml and the profiles directory, and injected into every agent's system prompt via :class:~dv_agentic.prompts.prompt_loader.PromptLoader.

Examples:

.. code-block:: shell

# Minimal: no profile injection
python3 -m dv_agentic.cli.orchestrator \
    --input-file task.txt \
    --simulator xcelium \
    --adapter imc

# Full: load team + IP profiles from project.yaml
python3 -m dv_agentic.cli.orchestrator \
    --project-config .agent/project.yaml \
    --profiles-dir ../team-profiles \
    --input-file task.txt
main()

Main execution block of the Orchestrator CLI.

Source code in src/dv_agentic/cli/orchestrator.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
def main() -> None:
    """Main execution block of the Orchestrator CLI."""
    args = _build_parser().parse_args()

    try:
        task_input = read_input(args.input_file)
    except OSError as exc:
        exit_with_error(str(exc))

    # --- Three-layer config ---
    project_ctx = None
    project_simulator = None
    project_coverage = None
    if args.project_config:
        try:
            from dv_agentic.config import load_project

            project_ctx, project_simulator, project_coverage = load_project(
                project_yaml=args.project_config,
                profiles_dir=args.profiles_dir,
            )
        except (FileNotFoundError, ValueError) as exc:
            exit_with_error(f"Failed to load project config: {exc}")

    try:
        from dv_agentic.agents.base import AgentConfig
        from dv_agentic.agents.orchestrator import OrchestratorAgent

        llm = make_llm(model=args.model)
        sub_agents = _build_sub_agents(
            args,
            llm,
            project_ctx=project_ctx,
            project_simulator=project_simulator,
            project_coverage=project_coverage,
        )

        agent = OrchestratorAgent(
            config=AgentConfig(name="orchestrator", budget=args.budget),
            llm=llm,
            sub_agents=sub_agents,
            project_config=project_ctx,
        )
        result = asyncio.run(agent.run(task_input))
        print(result)  # noqa: T201
    except Exception as exc:
        exit_with_error(str(exc))

Code Generator Command

code_generator

CLI entrypoint for CodeGeneratorAgent.

Examples:

.. code-block:: shell

python3 -m dv_agentic.cli.code_generator             --task-id cov_fix_001             --input-file task_description.txt
main()

Main execution block of the CodeGenerator CLI.

Source code in src/dv_agentic/cli/code_generator.py 
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def main() -> None:
    """Main execution block of the CodeGenerator CLI."""
    args = _build_parser().parse_args()

    if args.no_tb_guard:
        logger.warning(
            "============================================================\n"
            "SECURITY WARNING: Testbench guard is DISABLED (--no-tb-guard).\n"
            "The agent is allowed to write to any path in the workspace,\n"
            "including RTL source files. USE ONLY IN TEST ENVIRONMENTS!\n"
            "============================================================"
        )

    try:
        description = read_input(args.input_file)
    except OSError as exc:
        exit_with_error(str(exc))

    try:
        from dv_agentic.agents.base import AgentConfig
        from dv_agentic.agents.code_generator import (
            DEFAULT_TB_ALLOWED_DIRS,
            CodeGeneratorAgent,
            CodeTask,
        )

        llm = make_llm(model=args.model)
        agent = CodeGeneratorAgent(
            config=AgentConfig(name="code_generator", budget=args.budget),
            llm=llm,
            workspace_dir=".",
            # TB guard is ON by default; --no-tb-guard disables it
            allowed_dirs=None if args.no_tb_guard else DEFAULT_TB_ALLOWED_DIRS,
        )
        task = CodeTask(task_id=args.task_id, description=description)
        result = asyncio.run(agent.run(task))
        print(result)  # noqa: T201
    except Exception as exc:
        exit_with_error(str(exc))

Sim Controller Command

sim_controller

CLI entrypoint for SimControllerAgent.

Examples:

.. code-block:: shell

python3 -m dv_agentic.cli.sim_controller             --task-id cov_fix_001             --test axi_burst_test             --seed 42             --simulator xcelium
main()

Main execution block of the SimController CLI.

Source code in src/dv_agentic/cli/sim_controller.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def main() -> None:
    """Main execution block of the SimController CLI."""
    args = _build_parser().parse_args()

    try:
        from dv_agentic.agents.base import AgentConfig
        from dv_agentic.agents.sim_controller import SimControllerAgent
        from dv_agentic.tools.adapters import get_simulator_adapter
        from dv_agentic.tools.models import SimTask

        simulator = get_simulator_adapter(args.simulator)
        agent = SimControllerAgent(
            config=AgentConfig(name="sim_controller", budget=args.budget),
            simulator=simulator,
            base_branch=args.base_branch,
        )
        task = SimTask(
            task_id=args.task_id,
            test=args.test,
            seed=args.seed,
            file_list=args.file_list,
            top=args.top,
            debug=args.debug,
        )
        result = asyncio.run(agent.run(task))
        print(result)  # noqa: T201
    except Exception as exc:
        exit_with_error(str(exc))

Log Analyzer Command

log_analyzer

CLI entrypoint for LogAnalyzerAgent.

Examples:

.. code-block:: shell

python3 -m dv_agentic.cli.log_analyzer --input-file sim_test_42.log
python3 -m dv_agentic.cli.log_analyzer --input-file -         # read stdin
cat sim.log | python3 -m dv_agentic.cli.log_analyzer
main()

Main execution block of the LogAnalyzer CLI.

Source code in src/dv_agentic/cli/log_analyzer.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def main() -> None:
    """Main execution block of the LogAnalyzer CLI."""
    args = _build_parser().parse_args()

    try:
        content = read_input(args.input_file)
    except OSError as exc:
        exit_with_error(str(exc))

    from dv_agentic.agents.base import AgentConfig
    from dv_agentic.agents.log_analyzer import LogAnalyzerAgent

    agent = LogAnalyzerAgent(config=AgentConfig(name="log_analyzer"))
    result = asyncio.run(agent.run(content))
    print(result)  # noqa: T201

Specialty Commands

Spec Analyst Command

spec_analyst

CLI entrypoint for SpecAnalystAgent.

Examples:

.. code-block:: shell

python3 -m dv_agentic.cli.spec_analyst --input-file spec.txt --output-path .agent/vplan.yaml
main()

Main execution block of the SpecAnalyst CLI.

Source code in src/dv_agentic/cli/spec_analyst.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def main() -> None:
    """Main execution block of the SpecAnalyst CLI."""
    args = _build_parser().parse_args()

    try:
        spec_text = read_input(args.input_file)
    except OSError as exc:
        exit_with_error(str(exc))

    output_path = args.output_path

    try:
        from dv_agentic.agents.base import AgentConfig
        from dv_agentic.agents.spec_analyst import SpecAnalystAgent

        llm = make_llm(model=args.model)
        agent = SpecAnalystAgent(
            config=AgentConfig(name="spec_analyst", budget=args.budget),
            llm=llm,
            output_path=output_path,
        )
        result = asyncio.run(agent.run(spec_text))
        print(result)  # noqa: T201
    except Exception as exc:
        exit_with_error(str(exc))

Bug Classifier Command

bug_classifier

CLI entrypoint for BugClassifierAgent.

Examples:

.. code-block:: shell

python3 -m dv_agentic.cli.bug_classifier --input-file failure_summary.txt --threshold 0.75
cat failure.txt | python3 -m dv_agentic.cli.bug_classifier
main()

Main execution block of the BugClassifier CLI.

Source code in src/dv_agentic/cli/bug_classifier.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def main() -> None:
    """Main execution block of the BugClassifier CLI."""
    args = _build_parser().parse_args()

    try:
        failure_summary = read_input(args.input_file)
    except OSError as exc:
        exit_with_error(str(exc))

    try:
        from dv_agentic.agents.base import AgentConfig
        from dv_agentic.agents.bug_classifier import BugClassifierAgent

        llm = make_llm(model=args.model)
        agent = BugClassifierAgent(
            config=AgentConfig(name="bug_classifier", budget=args.budget),
            llm=llm,
            confidence_threshold=args.threshold,
        )
        result = asyncio.run(agent.run(failure_summary))
        print(result)  # noqa: T201
    except Exception as exc:
        exit_with_error(str(exc))

Coverage Analyst Command

coverage_analyst

CLI entrypoint for CoverageAnalystAgent.

Examples:

.. code-block:: shell

python3 -m dv_agentic.cli.coverage_analyst             --job-id my_test_42             --adapter imc             --threshold 90.0
main()

Main execution block of the CoverageAnalyst CLI.

Source code in src/dv_agentic/cli/coverage_analyst.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def main() -> None:
    """Main execution block of the CoverageAnalyst CLI."""
    args = _build_parser().parse_args()

    try:
        from dv_agentic.agents.base import AgentConfig
        from dv_agentic.agents.coverage_analyst import CoverageAnalystAgent
        from dv_agentic.tools.adapters import get_coverage_adapter

        coverage = get_coverage_adapter(args.adapter)
        agent = CoverageAnalystAgent(
            config=AgentConfig(name="coverage_analyst"),
            coverage=coverage,
            threshold=args.threshold,
        )
        result = asyncio.run(agent.run(args.job_id))
        print(result)  # noqa: T201
    except Exception as exc:
        exit_with_error(str(exc))

Reporter Command

reporter

CLI entrypoint for ReporterAgent.

Examples:

.. code-block:: shell

python3 -m dv_agentic.cli.reporter             --input-file session_results.txt             --output-path .agent/tasks/{task_id}_report.md
main()

Main execution block of the Reporter CLI.

Source code in src/dv_agentic/cli/reporter.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def main() -> None:
    """Main execution block of the Reporter CLI."""
    args = _build_parser().parse_args()

    try:
        session_results = read_input(args.input_file)
    except OSError as exc:
        exit_with_error(str(exc))

    output_path = args.output_path

    try:
        from dv_agentic.agents.base import AgentConfig
        from dv_agentic.agents.reporter import ReporterAgent

        llm = make_llm(model=args.model)
        agent = ReporterAgent(
            config=AgentConfig(name="reporter"),
            llm=llm,
            output_path=output_path,
        )
        result = asyncio.run(agent.run(session_results))
        print(result)  # noqa: T201
    except Exception as exc:
        exit_with_error(str(exc))

Environment Setup & Installer Command

install_agents

CLI entrypoint for the agent installer.

Generates enriched .agent/subagents/*.md files from the canonical prompt templates and creates symlinks for Claude Code, Cursor, and OpenCode.

What it does
  1. Optionally loads project.yaml + org profiles to enrich prompts (Level 1 injection: team rules + IP-type rules; session state omitted).
  2. For each of the agents, calls :class:~dv_agentic.prompts.prompt_loader.PromptLoader to produce an enriched prompt body (placeholders filled, unmatched removed).
  3. Strips the OpenCode-style YAML front matter from the source template.
  4. Prepends Claude Code / Cursor compatible YAML front matter.
  5. Writes to {worktree}/.agent/subagents/{agent}.md.
  6. Creates symlinks in .claude/agents/ and .cursor/rules/.

Examples:

.. code-block:: shell

# No profile injection — raw prompts only
python3 -m dv_agentic.cli.install_agents --worktree /path/to/project

# Full profile injection
python3 -m dv_agentic.cli.install_agents \
    --worktree /path/to/project \
    --project-config .agent/project.yaml \
    --profiles-dir ../team-profiles

# Overwrite existing files
python3 -m dv_agentic.cli.install_agents --force
install(worktree, project_yaml, profiles_dir, force)

Generate enriched subagent files and create symlinks.

Parameters:

Name Type Description Default
worktree Path

Root of the verification project (contains .agent/).

 required
project_yaml Path | None

Optional path to .agent/project.yaml.

 required
profiles_dir Path | None

Optional root of the org profile repository.

 required
force bool

Overwrite existing .md files if True.

 required

Returns:

Type Description
int

Exit code: 0 on success, 1 if any agent failed.
Source code in src/dv_agentic/cli/install_agents.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
def install(
    worktree: Path,
    project_yaml: Path | None,
    profiles_dir: Path | None,
    force: bool,
) -> int:
    """Generate enriched subagent files and create symlinks.

    Args:
        worktree: Root of the verification project (contains ``.agent/``).
        project_yaml: Optional path to ``.agent/project.yaml``.
        profiles_dir: Optional root of the org profile repository.
        force: Overwrite existing ``.md`` files if ``True``.

    Returns:
        Exit code: 0 on success, 1 if any agent failed.
    """
    # 1. Load ProjectContext (optional)
    project_ctx = None
    if project_yaml:
        try:
            from dv_agentic.config import load_project

            project_ctx, _, _ = load_project(
                project_yaml=project_yaml,
                profiles_dir=profiles_dir,
            )
            logger.info("Loaded project config from %s", project_yaml)
        except (FileNotFoundError, ValueError) as exc:
            logger.error("Failed to load project config: %s", exc)
            return 1

    # 2. PromptLoader — uses package-default prompts directory
    from dv_agentic.prompts.prompt_loader import PromptLoader

    loader = PromptLoader(project_config=project_ctx)

    # 3. Prepare output directories
    subagents_dir = worktree / ".agent" / "subagents"
    subagents_dir.mkdir(parents=True, exist_ok=True)

    symlink_dirs: list[Path] = []
    for rel in _SYMLINK_DIRS:
        d = worktree / rel
        d.mkdir(parents=True, exist_ok=True)
        symlink_dirs.append(d)

    # 4. Generate each agent
    errors = 0
    written = 0
    skipped = 0

    for agent_name in _AGENTS:
        target = subagents_dir / f"{agent_name}.md"

        if target.exists() and not force:
            logger.info("  skip  %s (exists — use --force to overwrite)", agent_name)
            skipped += 1
            continue

        # Load and enrich the prompt body
        try:
            enriched = loader.load(agent_name)
        except FileNotFoundError:
            logger.warning("  warn  %s — no prompt template found, skipping", agent_name)
            continue

        body = _strip_front_matter(enriched)
        meta = _AGENT_META.get(
            agent_name,
            {
                "description": f"{agent_name} agent.",
                "tools": ["Read"],
            },
        )
        content = _build_front_matter(agent_name, meta) + body.strip() + "\n"

        try:
            target.write_text(content, encoding="utf-8")
            logger.info("  wrote %s", target)
            written += 1
        except OSError as exc:
            logger.error("  error writing %s: %s", target, exc)
            errors += 1
            continue

        # Symlinks → relative path so they survive directory moves
        for link_dir in symlink_dirs:
            link = link_dir / f"{agent_name}.md"
            try:
                if link.exists() or link.is_symlink():
                    link.unlink()
                # Compute relative path from the symlink's directory to the target file
                rel_target = os.path.relpath(target, start=link_dir)
                link.symlink_to(rel_target)
            except OSError as exc:
                logger.warning("  warn  symlink %s → %s failed: %s", link, target, exc)

    # 5. Summary
    print(  # noqa: T201
        f"\nInstall complete: {written} written, {skipped} skipped, {errors} errors."
        f"\nSubagents: {subagents_dir}"
    )
    if symlink_dirs:
        for d in symlink_dirs:
            print(f"Symlinks:  {d}")  # noqa: T201

    return 0 if errors == 0 else 1
main()

Main execution block for the install-agents CLI.

Source code in src/dv_agentic/cli/install_agents.py 
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
def main() -> None:
    """Main execution block for the install-agents CLI."""
    args = _build_parser().parse_args()

    logging.basicConfig(
        level=logging.DEBUG if args.verbose else logging.INFO,
        format="%(message)s",
    )

    worktree = Path(args.worktree).resolve()
    project_yaml = Path(args.project_config).resolve() if args.project_config else None
    profiles_dir = Path(args.profiles_dir).resolve() if args.profiles_dir else None

    rc = install(
        worktree=worktree,
        project_yaml=project_yaml,
        profiles_dir=profiles_dir,
        force=args.force,
    )
    sys.exit(rc)