Skip to content

CLI Commands and Subcommands

In addition to the interactive REPL, Codaris provides non-interactive subcommands suitable for shell scripts, CI/CD runners, and headless automation. Every subcommand accepts --json, which prints one machine-readable JSON object instead of text, and exits with 0 on success, 1 on failure, and 2 when a required capability is unavailable.

The usual sequence for a new pipeline is doctor, plan, build, test, and review.

1. codaris doctor (alias codaris status)

Checks Nextflow, nf-core, Docker, seqtk, the toolchain container, and the versioned stores.

codaris doctor
codaris doctor --json

2. codaris stores check and codaris stores fetch

Verifies or downloads the versioned container and knowledge store artifacts that the compiler reads from. The stores are published as release artifacts because they exceed the in-repository size limit.

codaris stores check
codaris stores fetch --force

Options

  • --force: Re-download even when the local copies verify.
  • --base-url URL: Override the release base URL. The CODARIS_STORES_BASE_URL environment variable has the same effect.

3. codaris plan

Turns a natural-language prompt into a BuildPlan JSON. The planner resolves the assay, the module chain, and the reference assets, then asks a staged set of questions about references and test data.

codaris plan "Bulk RNA-seq for human paired-end FASTQ with STAR, Salmon, and MultiQC" \
  --interactive --out build_plan.json

Options

  • --out PATH: Where to write the plan (default build_plan.json).
  • --model NAME: Planner model override.
  • --playbooks-dir PATH: Directory of JSON playbooks (default: the bundled set).
  • --interactive: Ask the plan questions on the terminal one at a time; Enter accepts the default.
  • --answers FILE: Answer the plan questions from a JSON file keyed by question id.

Without --interactive or --answers, the planner writes <plan>.questions.json beside the plan with editable defaults. Licensed reference sources are only marked for download after an explicit acceptance.

4. codaris build

Compiles a pipeline directory from a BuildPlan JSON: main.nf, nextflow.config, modules, test configuration, and a sample sheet. The build runs nf_validate and nf-core pipelines lint before it returns.

codaris build build_plan.json --output-dir ./pipelines

Options

  • --output-dir PATH: Parent directory for the pipeline (default .).
  • --model NAME: Code-generation model override.
  • --self-review: After the build compiles and lints, have a second model read it against the six semantic criteria and apply one revision. CODARIS_SELF_REVIEW=1 has the same effect.
  • --confirm-nonstandard: Proceed past the non-standard-assay gate.
  • --use-defaults: Answer open reference questions with their defaults instead of refusing. A licensed source is never chosen this way.

A build with open blocking questions exits with code 2 unless --use-defaults is given.

5. codaris test

Runs a built pipeline's test profile with readiness checks, the resource fixer, and an optional LLM repair escalation.

codaris test ./pipelines/rnaseq
codaris test ./pipelines/rnaseq --llm-repair --llm-repair-budget 3

Options

  • --profile NAME: Nextflow profile (default test_codaris,docker).
  • --timeout SECONDS: Run timeout (default 3600).
  • --fix-budget N: Maximum resource-fixer attempts.
  • --skip-readiness: Skip the readiness scorecard before the run.
  • --llm-repair: When a failure the resource fixer cannot touch stops the run, escalate to an LLM-proposed patch against the pipeline's own generated files. CODARIS_LLM_REPAIR=1 has the same effect.
  • --llm-repair-budget N: Maximum LLM repair attempts (default 3).
  • --llm-repair-model NAME: Model for repair attempts (default: the build model).

Every repair attempt, applied or rejected, is recorded in .codaris/repair_log.json.

6. codaris review (alias codaris audit)

Read-only compliance audit. Writes a scorecard and a report without changing any file.

codaris review ./pipelines/rnaseq
codaris review ./pipelines/rnaseq --profile full --quick

Options

  • --profile core|full: Rule profile. core is the calibrated default set and full runs every rule.
  • --provider NAME: Provider override for the evaluator: any provider the chat can use (openai, anthropic, perplexity, google, azure, bedrock, local-api, local-anthropic). Without it the evaluator runs on the deployment's configured compliance model, the same one the chat resolves. In the chat the model cannot set a provider; the flag is for a person at the command line.
  • --model NAME: Proposer model override.
  • --quick: Deterministic checkers and nf-core lint only, skipping the AI evaluator. The report scores the rules those checkers decided, states how many rules were not evaluated, and gives no grade or certification verdict, since most of the rules need the evaluator. The data goes to docs/compliance-report.quick.json; the full audit's docs/compliance-report.json is never replaced by a quick run. A run in which no rule was evaluated, or on a directory that holds no main.nf or nextflow.config, exits 1; one where nf-core lint could not run still prints the scorecard but exits 2, since the lint findings are missing. Lint results already on disk from an earlier run (.codaris_lint.json) are reused and labelled as such.
  • --quiet: Omit the full Markdown report from stdout.

review writes nothing into the pipeline except the report file it prints the path of (docs/compliance-report.json, or docs/compliance-report.quick.json for --quick). nf-core lint runs on a throwaway copy, because the linter itself rewrites modules.json, conf/containers_*.config and the git index; the fix plan, the HTML report and the score history are written by remediate. When fewer than half of the checks produced a verdict (the evaluator could not answer the rest), the report says not graded: N of M checks evaluated and gives no letter.

Every scored report opens with one COMPLIANCE SUMMARY: line: the score, the grade or graded: no, the findings, the audit agreement, the checks evaluated and the files written. In the chat the same audit is /audit (or /review --compliance, and /review --quick for the quick pass). A bare /review in the chat is a different command: the structural wiring review (channels, params, containers, configs), with no scorecard.

7. codaris remediate

Applies rollback-safe compliance fixes and reports what changed. Originals are backed up in .codaris_fix_backups/ before any edit.

codaris remediate ./pipelines/rnaseq
codaris remediate ./pipelines/rnaseq --max-iterations 3

Options

  • --profile core|full, --provider, --model, --quick, --quiet: As for review.
  • --allow-destructive: Also run directives that are not rollback-safe.
  • --max-iterations N: Maximum fix-and-verify rounds (default 5).

8. codaris lint

Runs nf-core pipelines lint and classifies the result.

codaris lint ./pipelines/rnaseq --timeout 600

Options

  • --timeout SECONDS: Lint timeout (default 600).

9. codaris judge

Reads a built pipeline or a plan against the six semantic criteria and reports what is wrong.

codaris judge ./pipelines/rnaseq
codaris judge build_plan.json --criteria 1,3,5

Options

  • --criteria LIST: Comma-separated criterion numbers (default: all six).
  • --no-verify: Skip the refuter pass over blockers.
  • --quiet: Write the report and print nothing.

10. codaris nf-test

Writes a built pipeline's nf-test harness and CI job.

codaris nf-test ./pipelines/rnaseq --force

Options

  • --force: Replace files that are already present.

11. codaris publish

Copies a built pipeline and its record to a destination you specify.

codaris publish ./pipelines/rnaseq /shared/pipelines/rnaseq

Options

  • destination: Target path (default $CODARIS_PUBLISH_DIR/<name>).
  • --project NAME: The project whose record travels with the pipeline.
  • --pipeline NAME: Which of the project's pipelines to publish.

12. codaris bench

Benchmarks the bundled playbooks through plan, build, test, and review, and writes a scorecard.

codaris bench --only rnaseq --only wgs --out bench_scorecard.json

Options

  • --playbooks-dir PATH: Directory of JSON playbooks (default: the bundled set).
  • --out PATH: Scorecard JSON path (default bench_scorecard.json).
  • --only KEY: Benchmark only this playbook key (repeatable).
  • --work-dir PATH: Working directory for the sweep.
  • --reuse-work-dir: Build on top of a previous sweep's output. A scorecard produced this way may report modules an earlier run wrote, so treat it as an iteration aid rather than a measurement.
  • --skip-plan, --skip-build, --skip-test, --skip-review: Skip a stage.
  • --model NAME: Model override.

13. codaris chat

Starts the interactive conversational agent in the terminal. Running codaris with no arguments does the same thing, and any first argument that is not a known verb is treated as the opening prompt. See the Interactive REPL page.

codaris chat "Build an ATAC-seq pipeline with Bowtie2 and MACS2" --mode plan

Options

  • --model NAME: Model override.
  • --workspace PATH: Workspace directory (default: the current directory).
  • --mode build|plan|review: Initial execution mode (default build).
  • --verbose, -v: Show tool call signatures and tracing.

14. codaris web (aliases codaris ui, codaris serve)

Launches the web studio and the API service.

codaris web --host 127.0.0.1 --port 8000 --reload

Options

  • --host ADDRESS: Bind host (default 127.0.0.1).
  • --port PORT: Bind port (default 8000).
  • --reload: Enable auto-reload for development.