Before you start, prepare a valid project and an environment containing the workflow tools. The command line exposes project/configuration operations and the same workflow command builder used by the graphical interface.
1. Inspect the installed command#
Run bulkseq --help and bulkseq version. From an appropriate source environment, the documented installation is pip install -e ., which installs the graphical interface packages as well; there is no separate command-line-only installation.
bulkseq --help
bulkseq version
bulkseq project create --name study --workdir PATH
bulkseq project info -C PATH
bulkseq config show -C PATH
bulkseq samples show -C PATH2. Inspect and change configuration#
Configuration keys are validated before a write; an invalid key/value leaves the file unchanged. Use an explicit project path to avoid accidentally editing another project.
bulkseq config get deseq2.alpha -C PATH
bulkseq config set deseq2.alpha 0.01 -C PATH
bulkseq check -C PATH
bulkseq print-command -C PATH --mode dry-run
bulkseq run -C PATH --mode dry-run| Setting | What it changes | When to change it / example |
|---|---|---|
| -C / --project PATH | Selects the project; default is current directory. | Use an explicit path in automated work. |
| --json / --quiet | Controls machine-readable output and banner suppression. | Use --json for parsing rather than scraping formatted text. |
| --mode run / dry-run / resume | Selects execution, graph inspection or interrupted-work recovery. | Read the printed command before launching a long run. |
| --exec-profile local / slurm / kubernetes | Selects the execution target. | A profile name does not establish that a cluster is configured or accessible. |
Configured sample sheet#
bulkseq project info, bulkseq samples show, and bulkseq check read input.samples. Set that field to a path relative to the project or to an absolute path; the conventional config/samples.tsv is used only when it remains the configured value. samples show and check name a missing or malformed configured sheet; project info retains its zero-sample summary for an unreadable sheet.
On the local FASTQ route, check requires each named read file. Relative FASTQ cells are resolved against the selected project, so bulkseq check -C PATH works from another directory without changing the sheet. Pending reads are accepted only for SRA, count-matrix, microarray, and imported-results routes, which do not require local FASTQ inputs.
3. Run and inspect the exit status#
bulkseq run -C PATH
bulkseq run -C PATH --mode resumeThe command returns 0 on success, 2 for a usage error, 3 for a project or configuration it cannot use, 4 when bulkseq check finds a FAIL, 5 when the workflow fails and 130 when interrupted. Exit 1 means an unexpected error and comes with a traceback. bulkseq --help lists the same codes, and Exit codes and statuses gives each one with what to do next.
4. Prepare an HPC target explicitly#
For Slurm, edit workflow/profiles/site/slurm/config.yaml for your partition, account and walltime. The published profile uses jobs and cores of 16 and a default runtime of 240 minutes, but your site must approve suitable values. Inspect bulkseq print-command --exec-profile slurm before submitting. Compute nodes may lack outbound access; arrange permitted downloads and shared inputs first.
| Setting | What it changes | When to change it / example |
|---|---|---|
| jobs | Limits concurrently submitted work. | Reduce to fit site policy; it is not the number of biological samples. |
| cores | Also affects per-rule thread ceilings in the profile. | Do not reduce below required rule threads without understanding the executor’s effect. |
| runtime / partition / account | Controls scheduler placement and resource request. | Use current site values rather than copying another institution’s partition. |
| Kubernetes image / shared storage | Makes tools and inputs available inside pods. | The published baseline does not supply a proven ready-to-run image; executor selection alone is insufficient. |
Advanced: Windows paths and workflow updates
Local execution translates supported Windows/WSL paths to WSL2. Ordinary network shares are refused. Cluster profiles are not wrapped in WSL2. bulkseq run and the interface synchronize an outdated copied workflow by staging and verifying a complete copy. If a recorded digest disagrees with the project workflow, the run stops without overwriting files; review the edits or restore the recorded workflow. A copy without a valid digest is repaired only when its actual tree matches the bundled workflow; otherwise it stops for review. A valid legacy recorded workflow is upgraded with the original tree retained in a project-local backup. The run report records the execution-tree digest separately from the bundled-workflow identity. An interrupt is acted on during a quiet step as well, because output is drained on a reader thread: Ctrl-C sends the process tree TERM, allows up to eight seconds for Snakemake to release its lock, then sends KILL, and the command exits 130.