JBrowse CLI with Desktop

JBrowse Desktop opens a genome and its data files from your own disk, and a folder holding those files with a config.json that lists them opens in one step, with every track named and a starting view set. The JBrowse command-line tool, @jbrowse/cli, writes that folder. It records each file by a path relative to config.json, so Desktop resolves the paths against the folder on disk and a web server resolves them against the served config's URL. We:

• compress and index the data files
• build the config with add-assembly and add-track, and index gene names with text-index
• set a default view with set-default-session
• open the folder in JBrowse Desktop, then serve the same folder on the web

Prerequisites#

• Node.js 18 or newer
• JBrowse Desktop, or a web server if you want to serve the same folder

Install the CLI#

Install Node.js from NodeSource or NVM; the apt packages tend to be old.

npm install -g @jbrowse/cli
jbrowse --version

To avoid a global install, replace jbrowse with npx @jbrowse/cli in any command below.

Prepare indexed, compressed data files#

The CLI copies or references your data files as they are, and JBrowse reads indexed, compressed files, so prepare each input first: a bgzipped and faidx-indexed FASTA, a sorted and indexed BAM or CRAM, a bgzipped and tabixed VCF, GFF3, or BED. The web quickstart has the samtools / htslib recipe per format, and the commands below assume you have already run them.

Build a config directory with add-assembly and add-track#

Point every command at the same output directory with --out, which the CLI creates if needed. The first add-assembly writes myproject/config.json, and each later command edits that file in place:

jbrowse add-assembly GRCh38.fa.gz --name hg38 --load copy --out myproject
jbrowse add-track sample.bam --load copy --out myproject --name "My reads"
jbrowse add-track variants.vcf.gz --load copy --out myproject --name "My variants"
jbrowse add-track genes.gff3.gz --load copy --out myproject --name "My genes"

--name hg38 is the assembly name the session and the assembly selector use. --name on a track is its label in the track list.

--load sets how the CLI places a local file relative to the config:

myproject/ is now self-contained:

myproject/
├── config.json
├── GRCh38.fa.gz  (+ .fa.gz.fai, .fa.gz.gzi)
├── sample.bam    (+ .bam.bai)
├── variants.vcf.gz  (+ .vcf.gz.tbi)
└── genes.gff3.gz    (+ .gff3.gz.tbi)

"adapter": {
  "type": "BamAdapter",
  "bamLocation": { "uri": "sample.bam", "locationType": "UriLocation" },
  "index": {
    "location": { "uri": "sample.bam.bai", "locationType": "UriLocation" },
    "indexType": "BAI"
  }
}

Index gene names for search#

jbrowse text-index indexes the gene names into the same directory, so the location box finds a gene by name:

jbrowse text-index --out myproject

Open the folder on a default view with a session#

A config with tracks but no session displays nothing until you launch a view and tick tracks in the selector. To open the folder ready to read, write a session and hand it to the CLI. In the session:

• assembly is the --name you gave add-assembly
• tracks takes the trackIds the CLI derived from your filenames; jq '.tracks[].trackId' myproject/config.json prints them

{
  "name": "myproject",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:1-100,000",
      "tracks": ["sample", "variants.vcf"]
    }
  ]
}

jbrowse set-default-session --session session.json --out myproject

session.json stays outside the folder, and the CLI copies its contents into config.json. jbrowse validate myproject/config.json reports a misspelled key that JBrowse would otherwise ignore.

Open the CLI-built folder in JBrowse Desktop#

Choose File → Session → Open config.json or .jbrowse file... in JBrowse Desktop (or use the Open file or link button on the start screen) and pick myproject/config.json. Desktop resolves each relative path against the config's folder and loads the copied files from local disk, with no web server.

You can also hand the config straight to Desktop.¹ No installer puts it on the PATH, so call the binary by its path (per platform):

./jbrowse-desktop-*-linux.AppImage myproject/config.json  # Linux
open -a "JBrowse 2" myproject/config.json                 # macOS

Desktop reads config.json and never writes back to it. Desktop autosaves your work to a separate session in Recently opened sessions, with its own copy of the config. So after another add-track, reopen config.json itself to see the new track; the autosave still holds the old track list. Save session as... writes a .jbrowse file, which Desktop saves in place from then on.

Serve the config folder on the web#

JBrowse Web is a separate app, so a served myproject/ needs a JBrowse Web instance alongside it, set up either way:

• Build into a JBrowse Web install: run jbrowse create jbrowse2 first and pass --out jbrowse2 on the commands above, so the app and your config sit in one served folder. The web quickstart takes this route.
• Point an existing deployment at your config: host myproject/ anywhere (e.g. npx serve myproject) and open your JBrowse Web instance with its URL appended: https://your-jbrowse/?config=http://localhost:3000/config.json.

See also#

• Tutorial: Display settings
• Tutorial: Embedding JBrowse
• Config guide: Assemblies
• Docs: Command line tools (JBrowse CLI)
• Docs: JBrowse desktop quick start
• Docs: JBrowse web quick start

Feedback on this tutorial is welcome: contact us.