CLI and headless servers¶

OncoTracer can configure and run entirely in a terminal. On a server without a desktop, you can also connect your laptop browser through SSH.

While analysis runs, the terminal shows parallel sample progress. Tool output stays in the printed log file; the final table lists every sample and its completion status. Redirected output remains plain text without animated bars.

Check parallel sample-job options¶

oncotracer --detect-resources
# Equivalent: oncotracer --detect_resources
oncotracer --interactive --backend conda

The first command only reports hardware and suggests parallel samples × cores per sample, such as 5 jobs × 8 cores or 4 jobs × 10 cores when CPU and RAM allow. Choose the combination in setup. Both spellings require the current GitHub source. See sample-job planning and shared-server budgets.

Choose your setup route¶

Route	Command	What happens
Browser	`oncotracer --interactive --backend conda`	Starts the local setup server and opens a browser.
Terminal questions	`oncotracer setup --terminal`	Asks for inputs/settings in the terminal; finish with `save` or `run`.
Scripted setup	`oncotracer setup --non-interactive ...`	Writes configuration from explicit sample flags; no browser or questions.
Remote browser	`oncotracer setup --no-browser --port 8888`	Starts the setup server and prints its URL; connect through SSH below.
Saved analysis	`oncotracer run --backend conda --config /work/study/config/run.yml`	Runs saved settings in the terminal.

--no-browser still starts a web server. Use --terminal or --non-interactive for no web interface. There is no --headless flag.

Install the launcher and analysis tools on the server first. If oncotracer is not on PATH and you installed it in a virtual environment, activate that environment first. All read, reference, model, database and project paths belong to the server. Replace /data and /work paths with your own. Choose one setup route per new project.

Terminal questions¶

The equivalent of browsing an Illumina FASTQ folder:

oncotracer setup --terminal --project /work/illumina-study \
  --mode illumina --input-folder /data/illumina --backend conda

Assign sample names and Cancer/Normal roles. Choose save, then:

oncotracer check --config /work/illumina-study/config/run.yml
oncotracer run --backend conda --config /work/illumina-study/config/run.yml

For ONT, use a separate project. This version asks the remaining questions and then checks and runs in the same terminal:

oncotracer setup --terminal --run --project /work/ont-interactive \
  --mode ont --input-folder /data/run/fastq_pass --backend conda

Omit --run to choose save at the final question instead.

Scripted Illumina: setup, check and run¶

One paired-end library, with every sample choice supplied:

oncotracer setup --non-interactive \
  --project /work/illumina-scripted --mode illumina --analysis cna \
  --sample-name sampleA --status tumor \
  --fastq-1 /data/illumina/sampleA_R1.fastq.gz \
  --fastq-2 /data/illumina/sampleA_R2.fastq.gz \
  --backend conda --threads 8
oncotracer check --config /work/illumina-scripted/config/run.yml
oncotracer run --backend conda --config /work/illumina-scripted/config/run.yml

Omit --fastq-2 for single-end reads. For several libraries, replace the single-sample flags with --samplesheet /data/illumina/samplesheet.csv; use the four-column samplesheet. --input-folder is for interactive discovery and cannot be combined with --non-interactive.

Scripted ONT: setup, check and run¶

Each selected barcode includes all its FASTQ batches:

oncotracer setup --non-interactive \
  --project /work/ont-scripted --mode ont --analysis cna \
  --reads-folder /data/run/fastq_pass \
  --barcodes barcode01,barcode02 --sample-names sampleA,sampleB \
  --backend conda --threads 8
oncotracer check --config /work/ont-scripted/config/run.yml
oncotracer run --backend conda --config /work/ont-scripted/config/run.yml

Both scripted examples select CNA and automatic reference preparation at run time. To reuse a reference, add --hg38_build /data/shared-reference during setup. For ONT controls and sample roles, follow batch setup.

Docker without a browser¶

The launcher runs on the server; analysis runs in Docker. Install the Docker backend first. The pinned image below includes the variant runtimes as well as the CNA tools; this example requests only CNA. No host Conda is needed:

oncotracer setup --non-interactive \
  --project /work/docker-study --mode illumina --analysis cna \
  --sample-name sampleA --status tumor \
  --fastq-1 /data/illumina/sampleA_R1.fastq.gz \
  --fastq-2 /data/illumina/sampleA_R2.fastq.gz \
  --backend docker --image carlosfarkas/oncotracer:terminal-progress-20261022 \
  --threads 8
oncotracer check --config /work/docker-study/config/run.yml
oncotracer run --backend docker \
  --image carlosfarkas/oncotracer:terminal-progress-20261022 \
  --config /work/docker-study/config/run.yml

For variants, use the complete FFPE and ONT terminal examples, including caller/model paths. ANNOVAR also has terminal examples. For an existing-BAM variant YAML, use:

oncotracer variants --config /data/variants.yml --dry-run
oncotracer variants --config /data/variants.yml --threads 8

This command uses host tools and runtime paths in its variant YAML; it has no --backend option. It is the terminal counterpart of the existing-BAM browser form, setup --variant-config, which itself is browser-only.

Remote browser through SSH¶

On the server, start setup without launching a browser:

oncotracer setup --project /work/remote-study --backend conda \
  --no-browser --port 8888

On your laptop, open another terminal. Replace user@server with your SSH login:

ssh -N -o ExitOnForwardFailure=yes \
  -L 127.0.0.1:8888:127.0.0.1:8888 user@server

Open the entire URL printed on the server in your laptop browser, including the session code after #. Keep 127.0.0.1 and port 8888 exactly as printed: the server validates both. If the port is busy, choose another, such as 8890, in the server command and both port positions in the tunnel command. The server listens only on loopback; no public interface or firewall opening is needed.

Browse and Autodetect inspect the server, including its tools and databases. Follow the usual Save/check/Run steps. Keep the setup process and tunnel running while using the interface.

For remote existing-BAM settings, replace the server command with:

oncotracer setup --variant-config /data/variants.yml --no-browser --port 8888

Use the same tunnel. Terminal-only equivalent for that existing-BAM project:

oncotracer variants --config /data/variants.yml --dry-run
oncotracer variants --config /data/variants.yml --threads 8

Terminal-only equivalent for the remote FASTQ setup, with the same project and backend (answer its input/settings questions, then it checks and runs):

oncotracer setup --terminal --run --project /work/remote-study --backend conda

For unattended FASTQ execution, use the scripted Illumina or ONT blocks above.

Keep a long run open¶

If tmux is installed, create a persistent session on the server:

tmux new -s oncotracer

Inside that session, make sure the oncotracer command is available, then run:

mkdir -p /work/illumina-scripted/logs
set -o pipefail
oncotracer run --backend conda --config /work/illumina-scripted/config/run.yml \
  2>&1 | tee -a /work/illumina-scripted/logs/run.log

Detach with Ctrl+B, then D. Reconnect with tmux attach -t oncotracer. The setup server can also run inside tmux. Closing the browser or pressing Ctrl+C in the setup-server terminal leaves an already-started analysis running. Use Stop analysis in the interface, or Ctrl+C in a terminal running oncotracer run, to stop the analysis itself.

Read the result¶

tail -n 40 /work/illumina-scripted/logs/run.log
cat /work/illumina-scripted/results/06_workflow_summary/workflow_summary.txt

Continue an interrupted run¶

Fix the reported problem, then restart with the saved project:

oncotracer setup --project /work/illumina-scripted --run

This uses the project’s saved backend and reuses completed work. For settings changes and preview commands, see running details.

Complete examples¶

QuickStarts from the terminal provides complete setup/check/run commands for the verified downloads in both public tutorials. The full public cohort, batch setup, methylation guide, variant reference and ANNOVAR guide also include terminal runs.