Skip to content

Run Modes and Costs

This guide explains how to choose a Primr run mode, estimate cost, and understand which artifacts each command produces.

Always run --dry-run before billable work:

primr "Company" https://company.com --dry-run

Dry-run output is the source of truth for the next run. The numbers below are current guideposts for the common xAI plus Gemini setup, not guarantees.

Except for the Primr Zero row, this matrix describes direct terminal execution through Primr's provider-backed pipeline. A bare request in a capable agent chat defaults to Primr Zero; the same text entered in a terminal retains the provider-backed behavior.

Mode Matrix

The outcome column is the product distinction. It is not a page guarantee. Generated length varies with available evidence, model output limits, and the selected strategy modules.

Profile Command shape Outcome and writing topology Assurance Typical time Typical cost
Primr Zero in an agent host Ask the host: primr "Company" url Keyless Primr evidence bundle; the host writes the dossier Host-dependent synthesis; Primr collection remains model-free 5-15 min collection, then host-dependent $0.00 incremental model API spend when the host is plan-backed
OpenRouter Standard primr "Company" url with OpenRouter configured Strategic Overview plus integrated AI Strategy via OpenRouter gateway (Gemini 3.5 Flash-Lite, GPT-6 Luna, DeepSeek V4.1 Flash) Primr owns synthesis, artifact validation, usage, and recovery 25-45 min ~$0.68
Provider-backed Standard primr "Company" url in a terminal Strategic Overview plus one integrated AI Strategy; planned section batches followed by cross-validation and a guarded whole-document coherence pass Primr owns synthesis, artifact validation, usage, and recovery 34-53 min ~$1.26
Standard base report primr "Company" url --no-ai-strategy Strategic Overview through the same Standard report pipeline Same report assurance, without strategy generation 31-47 min ~$1.08
XAI-only Standard fallback primr "Company" url with only XAI configured Standard topology using the xAI writing and utility path Primr-owned, but materially more expensive than the measured two-provider recipe 34-53 min ~$5.99
XAI-only base fallback primr "Company" url --no-ai-strategy with only XAI configured Standard base report using the xAI path Same fallback assurance, without strategy generation 31-47 min ~$5.24
Standard MAX opt-in primr "Company" url --grok-tier max Standard topology with Grok 4.7 used for all model stages Explicit high-cost option; the base report is about $8.65 34-53 min ~$10.05 with the default strategy
Scrape primr "Company" url --mode scrape Site corpus plus provider-synthesized insights Provider-backed and billable; this is not Primr Zero 2-5 min ~$0.10
Deep primr "Company" url --mode deep Hiring evidence plus Deep Research dossier, sequential section expansion, and one AI Strategy Primr-owned Deep Research lifecycle and partial-result recovery 32-62 min ~$5.38 with the current static plan
Deep base report primr "Company" url --mode deep --no-ai-strategy Deep Research dossier and sequential section expansion without strategy generation Same Deep report path without the optional strategy task 24-47 min ~$2.88 with the current static plan
Premium primr "Company" url --premium Structured evidence plus Deep Research dossier, sequential Flash section writing, assembly, and one AI Strategy Maximum-depth provider-backed path; quality is evaluated separately from length 74-132 min ~$6.71 with the current static plan
Premium lite primr "Company" url --premium --lite Premium company report with a lighter strategy-generation path The report path remains Premium; the strategy stage uses the lite recipe 68-120 min ~$4.64 with the current static plan
Recon primr recon company.com DNS intelligence Deterministic, keyless 2-3 sec $0.00
Render primr render <file>.md DOCX + TXT from existing Markdown Deterministic rendering and structural validation <5 sec $0.00
Skill pack primr skills "Company" url Agent Skills tree plus Cowork zip Separate role-and-skill workflow, not a report-length tier ~3 min ~$0.30

There is no separate --long profile. Long-form sequential expansion is the current Deep/Premium behavior. Do not infer that --mode scrape is free: only primr prep and primr recon are the keyless collection paths in this table. Deep and Premium both include one AI Strategy by default, just like Standard. Add --no-ai-strategy when comparing base-report prices. The OpenRouter Standard cost is the 2026-10-12 dry-run display of the estimator total $1.0655. It does not assume prompt-cache savings and does not include OpenRouter credit-purchase fees. The live dry-run can be higher than the static plan when sufficient historical usage establishes a higher authorization floor.

First useful output (while a long run is still going)

Long provider-backed runs can take half an hour or more. Primr already has earlier, honest signals you can use without waiting for the full Strategic Overview:

When What to run or watch Notes
Seconds primr recon company.example DNS / tenant / email-security signals, $0 model
Minutes primr prep "Company" url Keyless evidence bundle for host-assisted synthesis
Mid-run Working folder + working brief After scrape (+ hiring refresh): free, incomplete brief
End of run Strategic Overview + optional AI Strategy Primary deliverables

Layer 1 working brief (shipped): after collection on the fast path and on structured/deep Phase 1 (premium/complete data collection), Primr writes a deterministic incomplete brief (no extra model calls) to working/<run>/working_brief.md and a dated public <Company>_Working_Brief_<date>.md under the run’s output_dir (or default output/). Pure --mode deep without a structured scrape may have no brief. Loud banner: not the Strategic Overview. Inventory role: working_brief (never primary_report). MCP job status includes body-free early_artifact_paths. Design: design/progressive-artifacts.md.

Default Provider Recipe

When both XAI_API_KEY and GEMINI_API_KEY are configured, Primr uses:

  • Grok for reasoning-heavy stages.
  • Gemini for bulk writing and utility stages.
  • DuckDuckGo search by default, which does not require a search API key.

This measured recipe is much cheaper than the older xAI-only path while preserving the trust gate used in evaluation. XAI-only runs still work. Their writing and utility stages use Grok 4.7.

OpenAI, Anthropic, and local OpenAI-compatible endpoints are wired into the provider layer for fallback, utility, evaluation, and planned backend-freedom routing. Full-report execution still uses the supported direct provider path described in API Key Setup.

Inference Profiles

--inference cloud is the default and preserves the validated direct-provider path. --inference hybrid enables the backend-freedom utility-stage pilots: fast.scrape_summary, fast.source_relevance, and fast.hiring_signals resolve their legacy utility models through the capability router, log safe route metadata, append body-free stage_routes entries to _run_state.json, and then execute through existing provider seams. The public CLI exposes only cloud and hybrid.

fast.source_relevance also has an unpromoted, experimental Codex CLI route. It remains disabled unless a single-company command includes both --inference hybrid and --acknowledge-host-agent-may-bill. Codex CLI authentication does not tell Primr whether a session uses plan allowance or metered billing, so the route is recorded as potentially_metered; its unknown host charge is excluded from --dry-run totals and --budget. The route uses a read-only sandbox with web search and shell tools disabled. If no runner qualifies, hybrid keeps the already-estimated cloud baseline. If a selected host execution fails, source filtering keeps all sources without making a second cloud call. This explicit pilot has not cleared its hybrid-vs-cloud promotion eval and is not a validated default. Batch use is rejected. Use primr-zero inside a verified plan-backed host for the supported plan-native path. Local profiles remain unexposed until stage adapters and evals clear the promotion bar.

Strategy Generation

The default command includes AI Strategy. Disable it when you only need the Strategic Overview:

primr "Company" https://company.com --no-ai-strategy

Platform targeting:

primr "Company" https://company.com --platform ms
primr "Company" https://company.com --platform aws azure

--platform ms explicitly expands to azure private, creates two strategy artifacts, and must be estimated as a two-platform run. Use --platform azure when only a Microsoft ecosystem emphasis is intended.

When --platform is omitted, Primr runs DNS recon first. No strong infrastructure signal produces one vendor-neutral AI Strategy. One strong ecosystem signal emphasizes that ecosystem in one strategy. Multiple strong ecosystem signals produce one integrated vendor-neutral strategy so the user does not receive an accidental artifact fan-out. Explicit multi-platform input still creates separate strategy artifacts and must be included in the estimate.

The default AI Strategy starts with business economics, an enterprise performance agenda, strategic tensions, industry direction, and value pools. It tests how AI could defend the core, improve operations, extend products and services, or create new business models before selecting technology. It then builds a prioritized portfolio and connects each initiative to measurable business outcomes, the complete observed technology and service stack, fully loaded unit economics, operating ownership, governance, and workload placement. Every initiative includes a non-AI alternative and opportunity cost. Every material observed ecosystem receives an explicit disposition rather than being silently omitted. Public cloud, multicloud, private or on-premises accelerated infrastructure, edge, and hybrid options are evaluated when the workload makes them material. A platform flag is an evaluation emphasis, not permission to ignore other detected ecosystems or skip credible alternatives.

Strategy types are YAML-defined and discovered at runtime:

primr --list-strategies
primr "Company" https://company.com --strategy-type customer_experience

Current selectable strategy documents include AI, customer experience, modern security and compliance, data fabric, and skills. Use primr skills for the skills pack workflow. primr --list-strategies is the installed source of truth; historical or placeholder YAML files are not selectable strategies.

MCP generate_strategy is a standalone post-report path backed by one Gemini Deep Research task per document. Its current planning estimate is about $2.50, including when strategy_type="skills"; call estimate_strategy for the live value. This differs from the fast in-pipeline YAML writer and from the QA-refined primr skills pack workflow shown in the mode matrix.

Cost Controls

Use the built-in control path:

primr "Company" https://company.com --dry-run --budget 10
primr "Company" https://company.com --budget 10
primr show-usage

--budget 10 is a $10 maximum for that run, not a target and not approval. Use it on the dry run to preview the decision, then keep the same ceiling on the exact approved launch. The human preview shows both values. JSON adds:

{
  "provider_ready": true,
  "execution_ready": true,
  "budget_enforcement": {
    "ceiling_usd": 10.0,
    "estimated_cost_usd": 1.07,
    "within_budget": true
  }
}

The example cost is the 2026-10-12 OpenRouter dry-run display. A live JSON preview reports the unrounded estimator total. provider_ready means the selected recipe has a usable provider. execution_ready additionally requires the estimate to fit the supplied ceiling. An over-ceiling preview sets within_budget and execution_ready to false, and launch refuses before model calls. Invalid, zero, negative, or non-finite ceilings also fail closed.

Authorization floor (CLI and MCP)

CLI dry-run, --budget, and launch quotes use the same shaping kwargs as execution. The dollar ceiling is max(planning defaults, historical averages) when enough samples exist, the same rule MCP/A2A already applied, so a few cheap past runs cannot under-approve a full recipe. Unknown estimator modes fail closed (they raise); product aliases such as full / deep / scrape map to internal mode names.

Dual-provider dry-run honesty

OpenAI- or Anthropic-only keys, without xAI, Gemini, or an explicitly enabled OpenRouter route, can still produce a full-mode planning quote. That quote is the XAI/Gemini full-recipe floor, not OpenAI/Anthropic live rates. Dry-run labels say estimate-only / keys required; --dry-run --json sets execution_ready: false and next steps point at configuring xAI or Gemini, or explicitly enabling a configured OpenRouter key before launch. An enabled OpenRouter route prices its registered role models directly.

Experimental primr orchestrate

primr orchestrate "Company" https://company.com --dry-run
primr orchestrate "Company" https://company.com --max-cost 5.0

Always prices first. Launch requires estimate ≤ --max-cost or interactive [y/N] yes (then a runtime CostGuardHook at estimate + 25%). Invalid or empty URLs fail closed after scheme normalization.

Cost behavior:

  • Dry-run estimates the run before model calls.
  • --budget refuses to start if the estimate exceeds the cap.
  • The per-run Primr ceiling is separate from any provider account or API-key spending limit. Use both when the provider supports an independent limit.
  • Fast full-report runs also consult runtime budget checkpoints before optional stages.
  • Premium, deep, and non-fast complete or hybrid runs checkpoint before and between optional strategy documents after the required Deep Research task completes.
  • Required Deep Research tasks cannot be stopped mid-flight by --budget; scrape remains estimate-gated only.
  • MCP tools require server-side cost caps and estimate-bound approval tokens by default on every transport.
  • Vendor-research generation (AI news) is freshness-aware and explicit: cached research is reused, but missing or stale cache files do not trigger a fresh refresh in estimate-bound runs unless you pass --refresh-vendor-research. The default refresh engine is grounded-lite (~$0.30, one Gemini plus Google Search grounded call, live and cited); --deep-research restores the thorough Deep Research engine (~$2.50/task). Dry-run and budget output then include one separate refresh task per selected platform. Use primr --generate-vendor-research <vendor> --dry-run to quote deliberate direct cache generation. The direct command aggregates all targets, honors --budget, requires confirmation unless --skip-confirm is supplied, and returns nonzero if any requested target fails. all covers Azure, AWS, GCP, private accelerated infrastructure, and vendor-neutral research. Ambient PRIMR_ALLOW_VENDOR_REFRESH applies only to direct library callers that leave policy environment-controlled; integrated CLI and MCP strategy paths override it off.
  • A fast run with --refresh-vendor-research preflights both XAI and Gemini credentials before starting the base pipeline. Multi-platform refresh tasks run serially, then the strategy-writing calls fan out in parallel.
  • Local dependency and configuration checks run before the cost gate. Network connectivity checks run only after the estimate is within --budget, so a refused run cannot make provider requests.
  • A completed base report and requested strategy artifacts have separate outcomes. If any explicitly requested strategy or refresh target fails or is budget-skipped, the report remains available, the run state and JSON result list each target outcome, and the CLI returns nonzero instead of hiding the partial result. JSON status describes the base artifact while fulfillment_status describes the whole request. Missing or malformed outcome state produces fulfillment_status: unknown and a nonzero exit. Human completion output and primr --check-jobs surface unresolved targets and the state path. Local monitoring also requires a canonical completed lifecycle and internally consistent outcome partitions before it reports completed fulfillment. Standalone multi-platform strategy generation follows the same all-target success rule.
  • Fast, deep, complete, hybrid, and standard summaries reconcile refresh tasks that actually reached provider submission. Standard mode also includes its AI Strategy Deep Research task. AI Strategy and refresh counts are run-local, so overlapping runs cannot claim one another's submissions. Refresh usage is not duplicated in the main run history because each submitted refresh records its own usage row.
  • The legacy non-fast structured runtime supports one AI Strategy platform. It rejects custom strategy types and multiple explicit platforms before any provider preflight; use complete mode or XAI fast mode for those shapes.
  • Gemini PDF extraction is off by default and local PyMuPDF parsing is used instead. Governed research runs reject the environment-only PRIMR_PDF_LLM_MAX_CALLS switch until those calls are estimate-bound.
  • primr skills emits local Cowork icons by default. Remote image generation requires --remote-icons or MCP remote_icons=true, and the estimate includes a conservative image allowance only when that opt-in is set.
  • primr show-usage ends with a per-mode "Cost Variability" section: it compares each mode's recent runs against its prior history (average cost, spread, and cache hit rate) and prints a report-only SIGNAL line when recent runs cost more or cache less than history. It never blocks a run; it surfaces continuous-reasoning or prompt-cache regressions that would otherwise erode the sub-$1 default silently.

Batch and Standalone Cost Gates

Batch research and website enrichment are separate governed operations:

primr --batch "companies.csv" --enrich --dry-run
primr --batch "companies_enriched.csv" --dry-run

Enrichment quotes only rows missing a website. It performs no search or model call before approval, pins the quoted utility model, disables retries and provider failover, and writes a reviewable CSV. Batch research requires a website for every pending company, quotes the entire pending batch, applies --budget to that total, runs local-only preflight after approval, and never silently retries a paid company run. Machine-readable --json is supported for these dry-run plans and emits exactly one JSON object.

Standalone strategy recovery has its own gate:

primr --ai-strategy-only "output/report.md" --dry-run

--ai-strategy-only defaults to the ~$1 Pro-model lite engine (2-3 min); add --deep-research to restore the thorough Deep Research engine (~$2.50/task). The estimate reflects the selected engine.

Without --dry-run, Primr emits the same estimate and asks for approval before it creates a private content-digest-verified report snapshot. A report changed during approval is rejected before strategy generation. Normal full Strategic Overviews are retained in strategy context up to a 200,000-character bound. For automation, --dry-run --json emits one primr.strategy-estimate.v1 object. Approved --json --skip-confirm execution emits one primr.strategy-result.v1 object with expected targets, successful artifacts, and failures. JSON execution without --skip-confirm returns a structured approval-required refusal and never prompts.

Governed improvement commands

Plain primr improve <path> performs deterministic local cleanup with zero model calls. It remains free and does not require approval. Its dry run reports the zero-call shape without changing the file.

primr improve <path> --improve-agentic and primr refine "Company" are model-backed. Run the exact command with --dry-run to see its bounded quote. Execution repeats the quote, requires explicit approval, and honors --budget. For automation, --dry-run --json emits one primr.improvement-estimate.v1 object; execution without --skip-confirm returns one structured approval_required refusal; approved execution emits one primr.improvement-result.v1 object. Refine quotes its maximum shape of nine section regenerations plus three bounded acceptance audits, then stops early when its existing quality conditions are met. Runtime reservations occur before each quoted model-backed stage so the accepted ceiling cannot be silently expanded.

Output Locations

Default output:

output/
working/<company>/<timestamp>/

Deliverables write flat into output/ with the company name in each filename; there is no output/<company>/ subfolder.

Common files:

<Company>_Strategic_Overview_<date>.md
<Company>_Strategic_Overview_<date>.docx
<Company>_AI_Strategy_<date>.md
run_manifest.json
scraped_content.txt
insights.json
dossier.json

Use --output-dir when you want client-facing deliverables in a specific folder:

primr "Company" https://company.com --output-dir "C:\Clients\Company"

With a custom output directory, Markdown and DOCX deliverables go there. TXT mirrors and validation diagnostics stay in the run diagnostics folder.

Rendering existing Markdown

primr render <file>.md exposes the internal renderer for host-written or Primr-Zero Markdown. It writes a .docx (plus a .txt unless --no-txt) beside the source file, or into --output-dir when given, with no model calls or network access. Use --title and --subtitle to set document metadata.

Example Run

Grok 4.7 hybrid, recon auto-detected Azure

PHASE 0/6: Recon
Done: 14 services, 8 insights, platform azure

PHASE 1/6: Data collection
Done: 251 links, 50 selected
Done: 48 of 50 pages scraped
Done: 31 external sources

PHASE 2/6: Research deepening
Done: 8 gaps identified, 12 additional sources

PHASE 3/6: Analysis
Done: structured workbook built

PHASE 4/6: Report writing
Done: 23 sections, 21,500 words

PHASE 5/6: Cross-validation
Done: 3 contradictions resolved
Trust: PASS, citations clean
Label Citations: 34/36 Confirmed/Reported cite a source

PHASE 6/6: AI Strategy
Done: strategy generated

Complete in 38m
output/ExampleCo_Strategic_Overview_04-10-2026.docx
PASS, 23 chapters, 48 citations, about $0.89