@jbrowse/cli 4.3.0 → 5.0.0-beta.10

package/README.md

@@ -13,7 +13,7 @@ or by using a script file.
 
 A simple script that does not use @jbrowse/cli at all may just look like this
 
-```
+```js
 const config = JSON.parse(fs.readFileSync('config.json', 'utf8'))
 // do something with config.tracks, config.assemblies, etc.
 fs.writeFileSync('config.json', JSON.stringify(config, null, 2))
@@ -43,7 +43,7 @@ npx @jbrowse/cli create myfolder
 It is likely preferable in most cases to install the tools globally with
 `npm install @jbrowse/cli -g` however
 
-```
+```text
 
 JBrowse CLI
 
@@ -54,12 +54,14 @@ COMMANDS
   create               Downloads and installs the latest JBrowse 2 release
   add-assembly         Add an assembly to a JBrowse 2 configuration
   add-track            Add a track to a JBrowse 2 configuration
+  validate             Check a configuration for errors, including ones JBrowse accepts silently
   text-index           Make a text-indexing file for any given track(s)
   admin-server         Start up a small admin server for JBrowse configuration
   upgrade              Upgrades JBrowse 2 to latest version
   make-pif             Creates pairwise indexed PAF (PIF), with bgzip and tabix
-  sort-gff             Helper utility to sort GFF files for tabix
-  sort-bed             Helper utility to sort BED files for tabix
+  make-density         Counts feature starts per bin into a bigWig density sidecar, with bedGraphToBigWig
+  sort-gff             Sort a GFF/GTF for tabix: sort -k1,1 -k4,4n, header kept on top
+  sort-bed             Sort a BED for tabix: sort -k1,1 -k2,2n, header kept on top
   add-connection       Add a connection to a JBrowse 2 configuration
   add-track-json       Add a track configuration directly from a JSON hunk
   remove-track         Remove a track configuration from a JBrowse 2 configuration
@@ -76,7 +78,7 @@ Use "jbrowse <command> --help" for more information about a command.
 
 ## jbrowse create
 
-```
+```text
 Downloads and installs the latest JBrowse 2 release
 
 Usage: jbrowse create [localPath] [options]
@@ -100,6 +102,8 @@ Options:
   -t, --tag                  Version of JBrowse 2 to install. Format is v1.0.0.
                              Defaults to latest
 
+Examples:
+
 # Download latest release from github, and put in specific path
 $ jbrowse create /path/to/new/installation
 
@@ -119,7 +123,7 @@ $ jbrowse create --listVersions
 
 ## jbrowse add-assembly
 
-```
+```text
 Add an assembly to a JBrowse 2 configuration
 
 Usage: jbrowse add-assembly <sequence> [options]
@@ -127,19 +131,19 @@ Usage: jbrowse add-assembly <sequence> [options]
 Options:
   -t, --type                 type of sequence, by default inferred from sequence
                              file
-                             
+
                              indexedFasta - An index FASTA (e.g. .fa or .fasta)
                              file; can optionally specify --faiLocation
-                             
+
                              bgzipFasta - A block-gzipped and indexed FASTA
                              (e.g. .fa.gz or .fasta.gz) file; can optionally
                              specify --faiLocation and/or --gziLocation
-                             
+
                              twoBit - A twoBit (e.g. .2bit) file
-                             
+
                              chromSizes - A chromosome sizes (e.g. .chrom.sizes)
                              file
-                             
+
                              custom - Either a JSON file location or inline JSON
                              that defines a custom sequence adapter; must
                              provide --name if using inline JSON [choices:
@@ -191,13 +195,21 @@ Options:
                              any file operations [choices: copy, symlink, move,
                              inPlace]
 
-      --skipCheck            Don't check whether or not the sequence file or URL
-                             exists or if you are in a JBrowse directory
+  -f, --force                Overwrite existing assembly and skip file existence
+                             checks
+
+      --config               Any extra config settings to add to the assembly
 
-      --overwrite            Overwrite existing assembly if one with the same
-                             name exists
+Notes:
 
-  -f, --force                Equivalent to `--skipCheck --overwrite`
+--config takes inline JSON (not a file path) that is merged into the generated
+assembly config, so you can set fields the dedicated flags do not cover. A
+"sequence" object in it is merged into the generated ReferenceSequenceTrack
+rather than replacing it, e.g. --config
+'{"sequence":{"formatAbout":{"hideUris":true}}}' hides file URIs in the
+assembly's About dialog.
+
+Examples:
 
 # add assembly to installation in current directory. assumes .fai file also exists, and copies GRCh38.fa and GRCh38.fa.fai to current directory
 $ jbrowse add-assembly GRCh38.fa --load copy
@@ -222,21 +234,26 @@ $ jbrowse add-assembly https://example.com/data/sample.2bit
 
 # add a bgzip indexed fasta inferred by fa.gz extension. assumes .fa.gz.gzi and .fa.gz.fai files also exists
 $ jbrowse add-assembly myfile.fa.gz --load copy
+
+# hide file URIs in the assembly About dialog
+$ jbrowse add-assembly GRCh38.fa --load copy --config '{"sequence":{"formatAbout":{"hideUris":true}}}'
 ```
 
 
 ## jbrowse add-track
 
-```
+```text
 Add a track to a JBrowse 2 configuration
 
 Usage: jbrowse add-track <track> [options]
 
 Options:
-  -h, --help                 
+  -h, --help                 Show help
 
   -t, --trackType            Type of track, by default inferred from track file
 
+      --adapterType          Adapter type, by default inferred from track file
+
   -n, --name                 Name of the track. Will be defaulted to the trackId
                              if none specified
 
@@ -245,13 +262,32 @@ Options:
   -d, --description          Optional description of the track
 
   -a, --assemblyNames        Assembly name or names for track as comma separated
-                             string
+                             string. For pairwise synteny tracks the order is
+                             query,target (reverse of minimap2/nucmer argument
+                             order); for the multi-genome PAF adapters
+                             (MultiGenomePAFAdapter/MultiGenomeIndexedPAFAdapter)
+                             list every assembly the file covers, in any order
 
       --category             Optional comma separated string of categories to
                              group tracks
 
       --config               Any extra config settings to add to a track
 
+      --color                Track color: a plain CSS color or a jexl callback.
+                             Merged into displayDefaults
+
+      --height               Track display height in pixels. Merged into
+                             displayDefaults
+
+      --displayDefaults      Inline JSON merged into the track displayDefaults
+                             (labels, mouseover, filter, etc.)
+
+      --multiwig             Build a MultiQuantitativeTrack from several BigWigs
+                             (in place of the positional track arg): a
+                             comma-separated list of BigWig files/URLs, or a
+                             .json file holding an array of BigWig locations or
+                             subadapter objects, each with its own name/color
+
       --target               Path to config file in JB2 installation to write
                              out to
 
@@ -263,15 +299,11 @@ Options:
       --trackId              trackId for the track, by default inferred from
                              filename
 
-  -l, --load                 How to manage the track (copy, symlink, move,
-                             inPlace)
-
-      --skipCheck            Skip check for whether file or URL exists
-
-      --overwrite            Overwrites existing track if it shares the same
-                             trackId
+  -l, --load                 How to manage the track file relative to
+                             config.json. Required for local files, omit for
+                             URLs [choices: copy, symlink, move, inPlace]
 
-  -f, --force                Equivalent to --skipCheck --overwrite
+  -f, --force                Overwrite existing track and any existing files
 
       --protocol             Force protocol to a specific value
 
@@ -279,6 +311,53 @@ Options:
 
       --bed2                 Used only for mcscan anchors/simpleAnchors types
 
+      --density              Path or URL of a features-per-bin bigWig (jbrowse
+                             make-density) to attach as the adapter's
+                             densityAdapter. A local <file>.density.bw beside
+                             the track file is attached without this flag
+
+Notes:
+
+--load controls how the data file is placed relative to config.json: copy, move,
+or symlink it into the install directory, or inPlace to reference a pre-staged
+local file where it already sits. Omit --load entirely for URLs. For a local
+file the matching index is whichever conventional spelling is actually beside it
+— <file>.bai/.crai/.tbi, a <file>.csi, or the reads.bai form Picard writes
+beside reads.bam. A URL cannot be checked, so it gets <file>.bai/.tbi; pass
+--indexFile for anything else.
+
+--config takes inline JSON (not a file path) that is merged into the generated
+track config, so you can set fields the dedicated flags do not cover, e.g.
+--config '{"metadata":{"skipTextIndex":true}}' to exclude the track from jbrowse
+text-index.
+
+--color and --height set the two most common appearance settings without writing
+JSON. Wrap the value in single quotes and use double quotes inside a jexl
+callback so nothing needs escaping, e.g. --color
+'jexl:feature.strand==1?"blue":"red"'. --displayDefaults takes inline JSON for
+any other appearance setting (labels, mouseover, filter).
+
+--multiwig bundles several BigWigs into one MultiQuantitativeTrack, in place of
+the positional track argument: pass a comma-separated list of BigWig files/URLs,
+or a .json file with an array of BigWig locations or subadapter objects (each
+carrying its own name/color/group). With --load, local list entries are copied
+like any other track file.
+
+--density attaches a features-per-bin bigWig (jbrowse make-density) as the
+adapter's densityAdapter, the band a display draws where the region is too large
+to fetch features. A local <file>.density.bw beside the track file is attached
+without the flag; a URL cannot be probed, so a remote sidecar needs it. The
+adapters carrying the slot are BamAdapter, CramAdapter, HtsgetBamAdapter,
+Gff3TabixAdapter, GtfTabixAdapter, BedTabixAdapter, BigBedAdapter,
+VcfTabixAdapter and SplitVcfTabixAdapter.
+
+For pairwise synteny adapters (PAF/Delta/Chain) --assemblyNames is query,target
+— the reverse of the minimap2/nucmer input order. For the multi-genome PAF
+adapters (MultiGenomePAFAdapter, MultiGenomeIndexedPAFAdapter) it is instead the
+full list of assemblies the file covers, in any order.
+
+Examples:
+
 # copy /path/to/my.bam and /path/to/my.bam.bai to current directory and adds track to config.json
 $ jbrowse add-track /path/to/my.bam --load copy
 
@@ -296,12 +375,90 @@ $ jbrowse add-track https://mywebsite.com/my.bam
 
 # --load inPlace adds a track without doing file operations
 $ jbrowse add-track /url/relative/path.bam --load inPlace
+
+# color a track by strand and set its height (no escaping: single-quote the value, double-quote inside the jexl)
+$ jbrowse add-track genes.gff3.gz --load copy --color 'jexl:feature.strand==1?"blue":"red"' --height 200
+
+# bundle several BigWigs into one MultiQuantitativeTrack (no positional track arg)
+$ jbrowse add-track --multiwig a.bw,b.bw,c.bw --load copy --name "Coverage"
+
+# ...or from a sources.json carrying per-row name/color for each BigWig
+$ jbrowse add-track --multiwig sources.json --name "CATlas ATAC"
+
+# attach a remote density sidecar (a local genes.gff3.density.bw needs no flag)
+$ jbrowse add-track https://mywebsite.com/genes.gff3.gz --density https://mywebsite.com/genes.gff3.density.bw
 ```
 
 
-## jbrowse text-index
+## jbrowse validate
+
+```text
+Check a JBrowse configuration for errors, including the ones JBrowse itself
+accepts silently
+
+Usage: jbrowse validate [config.json] [options]
+
+Options:
+      --json                 Output the findings as JSON instead of text
+
+  -q, --quiet                Only print errors, suppressing warnings and notes
+
+  -h, --help                 Show help
+
+Notes:
+
+A config key JBrowse does not recognize is ignored rather than reported, so a
+misspelled slot leaves the track loading normally with the setting doing
+nothing. That is what this command is mainly for.
+
+Two levels are reported:
+
+  error    JBrowse silently does the wrong thing, or refuses to load it — an    
+       unknown slot, a key a defaultSession view or display does not           
+declare, a track naming an assembly the config never defines, a           
+defaultSession naming a trackId that does not exist, a duplicate           
+trackId. Exits 1.
+
+  warning  JBrowse will complain by itself on load, or handles it — a type name 
+          the core plugins do not register (expected if one of your plugins     
+      registers it), or a legacy key a migration rewrites, such as a view       
+    nesting its settings under "init". Never fails the run.
+
+A LinearMarkDisplay loads whenever its keys and value types are right and says
+what it cannot draw in a corner notice rather than refusing the track. This
+command runs the display's own rule list over every "marks" list in the file: an
+error where a mark draws nothing, never draws or a step cannot run, and a
+warning where a slot waits unread or the marks draw in an arrangement the author
+may not have meant. With --json each finding carries the stable "rule" id of the
+rule that made it.
+
+Types registered by plugins are not known to this command, so they come through
+as warnings rather than errors.
+
+The same checks are published as a JSON Schema at
+https://jbrowse.org/jb2/schema/v5/config.json: a "$schema" line naming it at the
+top of a config.json gives an editor completion and validation for every slot.
+This command runs that schema first, then the cross-references a schema cannot
+express — a trackId a session names that no track defines, an assembly a track
+names that none defines.
 
+Examples:
+
+# check the config.json in the current directory
+$ jbrowse validate
+
+# check a specific config or saved session
+$ jbrowse validate /path/to/config.json
+$ jbrowse validate mysession.jbrowse
+
+# machine-readable output
+$ jbrowse validate config.json --json
 ```
+
+
+## jbrowse text-index
+
+```text
 Make a text-indexing file for any given track(s).
 
 Usage: jbrowse text-index [options]
@@ -314,7 +471,9 @@ Options:
                              available tracks
 
       --excludeTracks        Specific tracks to exclude from indexing, formatted
-                             as comma separated trackIds
+                             as comma separated trackIds. To exclude a track
+                             permanently, set metadata.skipTextIndex on it in
+                             config.json instead (see Notes)
 
       --target               Path to config file in JB2 installation directory
                              to read from.
@@ -322,7 +481,7 @@ Options:
       --out                  Synonym for target
 
       --attributes           Comma separated list of attributes to index
-                             [default: Name,ID]
+                             [default: Name,ID,symbol]
 
   -a, --assemblies           Specify the assembl(ies) to create an index for. If
                              unspecified, creates an index for each assembly in
@@ -335,8 +494,13 @@ Options:
 
       --perTrack             If set, creates an index per track [default: false]
 
-      --exclude              Adds gene type to list of excluded types [default:
-                             CDS,exon]
+      --exclude              Comma separated list of feature types to exclude
+                             from indexing [default: CDS,exon]
+
+      --include              Comma separated list of feature types to index,
+                             dropping every other type. Unset by default, which
+                             indexes every type --exclude does not name. GFF3
+                             only
 
       --prefixSize           Specify the prefix size for the ixx index. We
                              attempt to automatically calculate this, but you
@@ -355,6 +519,34 @@ Options:
       --dryrun               Just print out tracks that will be indexed by the
                              process, without doing any indexing
 
+Notes:
+
+Individual tracks in config.json can be permanently excluded from indexing by
+setting "metadata": { "skipTextIndex": true } on the track. Such tracks are
+skipped even when indexing all tracks or a whole assembly, so you do not have to
+pass --excludeTracks on every run.
+
+Only tracks with an indexable adapter type (Gff3Adapter, Gff3TabixAdapter,
+GtfAdapter, GtfTabixAdapter, VcfAdapter, VcfTabixAdapter) are indexed; tracks
+with other adapter types are skipped automatically.
+
+GTF has no Name/ID attributes, so the default --attributes also match their GTF
+spellings (gene_name, transcript_name, gene_id, transcript_id). A GFF3 row with
+no Name, as in GENCODE, is named by its own gene_name or transcript_name.
+
+--exclude names types not to index; --include names the only types to index.
+Reach for --include when the file draws from a vocabulary you do not control: an
+NCBI RefSeq GFF3 uses 115 feature types, 80 of them leaf records with no name to
+search (a match is labelled with a bare UUID, a cDNA_match with an MD5, every
+biological_region with the string "biological region"), so a deny list leaks
+whichever type is added next while the allow list — gene, pseudogene and the
+transcript types — does not grow. Both may be given: --include admits, --exclude
+then narrows. Either can also be set per track in config.json as
+textSearching.indexingFeatureTypesToInclude / indexingFeatureTypesToExclude,
+which takes precedence over the flag.
+
+Examples:
+
 # indexes all tracks that it can find in the current directory's config.json
 $ jbrowse text-index
 
@@ -362,7 +554,7 @@ $ jbrowse text-index
 $ jbrowse text-index --tracks=track1,track2,track3
 
 # indexes all tracks except specific trackIds
-$ jbrowse text-index --exclude-tracks=track1,track2,track3
+$ jbrowse text-index --excludeTracks=track1,track2,track3
 
 # indexes all tracks in a directory's config.json or in a specific config file
 $ jbrowse text-index --out /path/to/jb2/
@@ -377,29 +569,54 @@ $ jbrowse text-index --file myfile.gff3.gz --file myfile.vcfgz --out indexes
 
 ## jbrowse admin-server
 
-```
+```text
 Start up a small admin server for JBrowse configuration
 
 Usage: jbrowse admin-server [options]
 
 Options:
-  -h, --help                 
+  -h, --help                 Show help
 
   -p, --port                 Specified port to start the server on (default:
                              9090)
 
+      --host                 Interface to bind to (default: 127.0.0.1). Use
+                             0.0.0.0 to accept connections from other machines
+
       --root                 Path to the root of the JB2 installation
 
       --bodySizeLimit        Size limit of the update message (default: 25mb)
 
+Notes:
+
+The admin-server lets a browser session write changes back to config.json on
+disk, authorized by a one-time key printed in the startup URL. It binds to
+127.0.0.1 so only this machine can reach it. The key gates the config routes,
+but the rest of the JBrowse directory is served unauthenticated, so widen --host
+only on a trusted network.
+
+Examples:
+
+# start the admin server for the JBrowse install in the current directory
 $ jbrowse admin-server
+
+# start on a specific port
 $ jbrowse admin-server -p 8888
+
+# point at a specific JBrowse installation directory
+$ jbrowse admin-server --root /path/to/jb2/
+
+# raise the body size limit for very large config updates
+$ jbrowse admin-server --bodySizeLimit 100mb
+
+# accept connections from other machines on the network
+$ jbrowse admin-server --host 0.0.0.0
 ```
 
 
 ## jbrowse upgrade
 
-```
+```text
 Upgrades JBrowse 2 to latest version
 
 Usage: jbrowse upgrade [localPath] [options]
@@ -423,6 +640,8 @@ Options:
 
   -u, --url                  A direct URL to a JBrowse 2 release
 
+Examples:
+
 # Upgrades current directory to latest jbrowse release
 $ jbrowse upgrade
 
@@ -445,34 +664,135 @@ $ jbrowse upgrade --nightly
 
 ## jbrowse make-pif
 
-```
+```text
 creates pairwise indexed PAF (PIF), with bgzip and tabix
 
 Usage: jbrowse make-pif <file> [options]
 
 Options:
-  -h, --help                 
+  -h, --help                 Show help
 
       --out                  Where to write the output file. will write
                              ${file}.pif.gz and ${file}.pif.gz.tbi
 
       --csi                  Create a CSI index for the PIF file instead of TBI
 
-$ jbrowse make-pif input.paf # creates input.pif.gz in same directory
+      --coarse               Accuracy bound (bp) of the coarse tier. A coarse
+                             row replaces its CIGAR with a coarse CIGAR (cr:Z:)
+                             that keeps every indel longer than half this length
+                             and folds the rest into runs, each run staying
+                             within this many bp of the real alignment. Defaults
+                             to 10000. The coarse tier (prefix T/Q) is emitted
+                             alongside the per-row CIGAR fine tier by default so
+                             whole-genome synteny views can auto-switch to it;
+                             pass --no-coarse to omit it.
+
+      --no-coarse            Do not emit the coarse tier; write only the per-row
+                             CIGAR fine tier.
+
+      --threads              Compression threads for bgzip. Defaults to 4. Raise
+                             it on a machine with cores to spare, or set 1 to
+                             leave the rest of the machine alone.
+
+Notes:
+
+Use --csi for assemblies containing sequences longer than ~512 Mb. The default
+TBI index cannot address coordinates beyond 2^29 (~536 Mb), so a CSI index is
+required for large chromosomes (e.g. some plant and amphibian genomes). Requires
+sh, sort, bgzip, and tabix on the PATH.
+
+Examples:
+
+# creates input.pif.gz and input.pif.gz.tbi in the same directory
+$ jbrowse make-pif input.paf
 
-$ jbrowse make-pif input.paf --out output.pif.gz # specify output file, creates output.pif.gz.tbi also
+# specify the output file, also creates output.pif.gz.tbi
+$ jbrowse make-pif input.paf --out output.pif.gz
+
+# use a CSI index for assemblies with chromosomes longer than ~512 Mb
+$ jbrowse make-pif input.paf --csi
+
+# a looser coarse tier: runs within 50kb of the alignment, indels over 25kb kept
+$ jbrowse make-pif input.paf --coarse 50000
+
+# emit only the per-row CIGAR fine tier, skipping the coarse tier
+$ jbrowse make-pif input.paf --no-coarse
+
+# give bgzip more (or fewer) compression threads than the default 4
+$ jbrowse make-pif input.paf --threads 8
 ```
 
 
-## jbrowse sort-gff
+## jbrowse make-density
+
+```text
+Counts feature starts per bin into a bigWig, the density sidecar a track draws
+where the region is too large to fetch its features
+
+Usage: jbrowse make-density <file> [options]
+
+Options:
+  -h, --help                 Show help
+
+      --bin                  Width of each bin, in bp [default: 1000]
+
+      --chrom-sizes          Two-column reference name and length table for the
+                             assembly the file is on
+
+      --assembly             FASTA of the assembly the file is on; its .fai
+                             supplies the reference lengths, in place of
+                             --chrom-sizes
+
+      --out                  Where to write the bigWig. Defaults to
+                             <file>.density.bw beside the input, which is where
+                             add-track looks for it
+
+Notes:
+
+The sidecar is attached to a track through its adapter's densityAdapter slot,
+which BamAdapter, CramAdapter, HtsgetBamAdapter, Gff3TabixAdapter,
+GtfTabixAdapter, BedTabixAdapter, BigBedAdapter, VcfTabixAdapter and
+SplitVcfTabixAdapter declare. add-track attaches it on its own when the default
+<file>.density.bw sits beside the track file, so building it before adding the
+track is all it takes; --density attaches one by path or URL.
+
+GFF3 counts only top-level features — a line whose attributes carry no Parent= —
+so a gene is one count rather than one per exon. GTF, BED and VCF have no parent
+link to follow, so every record counts.
 
+BAM and CRAM are out of scope: read depth is not feature density, and the tools
+that compute it already write bigWig. Point add-track --density at what they
+produce.
+
+Requires bedGraphToBigWig (UCSC) on the PATH.
+
+Examples:
+
+# writes genes.gff3.density.bw beside the input, in 1kb bins
+$ jbrowse make-density genes.gff3.gz --chrom-sizes hg38.chrom.sizes
+
+# take the reference lengths from the assembly FASTA index instead
+$ jbrowse make-density variants.vcf.gz --assembly hg38.fa
+
+# coarser bins, and a name of your own
+$ jbrowse make-density genes.gff3.gz --assembly hg38.fa --bin 10000 --out genes.10kb.bw
 ```
-Helper utility to sort GFF files for tabix. Moves all lines starting with # to the top of the file, and sort by refname and start position using unix utilities sort and grep
+
+
+## jbrowse sort-gff
+
+```text
+Sort a GFF or GTF for tabix — the two share a refname/start column layout. It is
+`sort -k1,1 -k4,4n` with LC_ALL=C and a tab separator, plus every line starting
+with # kept at the top rather than sorted into the data. Takes a file, or the
+same data on stdin
 
 Usage: jbrowse sort-gff [file] [options]
 
 Options:
-  -h, --help                 
+  -h, --help                 Show help
+
+Examples:
 
 # sort gff and pipe to bgzip
 $ jbrowse sort-gff input.gff | bgzip > sorted.gff.gz
@@ -480,18 +800,26 @@ $ tabix sorted.gff.gz
 
 # sort gff from stdin
 $ cat input.gff | jbrowse sort-gff | bgzip > sorted.gff.gz
+
+# also works on GTF
+$ jbrowse sort-gff input.gtf | bgzip > sorted.gtf.gz
+$ tabix -p gff sorted.gtf.gz
 ```
 
 
 ## jbrowse sort-bed
 
-```
-Helper utility to sort BED files for tabix. Moves all lines starting with # to the top of the file, and sort by refname and start position using unix utilities sort and grep
+```text
+Sort a BED file for tabix. It is `sort -k1,1 -k2,2n` with LC_ALL=C and a tab
+separator, plus every line starting with # kept at the top rather than sorted
+into the data. Takes a file, or the same data on stdin
 
 Usage: jbrowse sort-bed [file] [options]
 
 Options:
-  -h, --help                 
+  -h, --help                 Show help
+
+Examples:
 
 # sort bed and pipe to bgzip
 $ jbrowse sort-bed input.bed | bgzip > sorted.bed.gz
@@ -503,13 +831,13 @@ $ tabix sorted.bed.gz
 
 ## jbrowse add-connection
 
-```
+```text
 Add a connection to a JBrowse 2 configuration
 
 Usage: jbrowse add-connection <connectionUrlOrPath> [options]
 
 Options:
-  -h, --help                 
+  -h, --help                 Show help
 
   -t, --type                 Type of connection (e.g. JBrowse1Connection,
                              UCSCTrackHubConnection, custom)
@@ -532,31 +860,41 @@ Options:
 
       --out                  Synonym for target
 
-      --skipCheck            Don't check whether the data directory URL exists
+  -f, --force                Overwrite existing connection if one with the same
+                             id exists
 
-      --overwrite            Overwrites any existing connections if same
-                             connection id
+Examples:
 
-  -f, --force                Equivalent to --skipCheck --overwrite
+# add a JBrowse 1 data directory connection (type inferred from the jbrowse/data path)
+$ jbrowse add-connection https://mysite.com/jbrowse/data/ -a hg19
 
-$ jbrowse add-connection http://mysite.com/jbrowse/data/ -a hg19
-$ jbrowse add-connection http://mysite.com/jbrowse/custom_data_folder/ --type JBrowse1Connection -a hg38
-$ jbrowse add-connection http://mysite.com/path/to/hub.txt
-$ jbrowse add-connection http://mysite.com/path/to/custom_hub_name.txt --type UCSCTrackHubConnection
-$ jbrowse add-connection http://mysite.com/path/to/custom --type custom --config '{"uri":{"url":"https://mysite.com/path/to/custom"}, "locationType": "UriLocation"}' -a hg19
+# force the JBrowse1Connection type for a non-standard data folder path
+$ jbrowse add-connection https://mysite.com/jbrowse/custom_data_folder/ --type JBrowse1Connection -a hg38
+
+# add a UCSC track hub (type inferred from the hub.txt filename)
+$ jbrowse add-connection https://mysite.com/path/to/hub.txt
+
+# force the UCSCTrackHubConnection type for a hub file not named hub.txt
+$ jbrowse add-connection https://mysite.com/path/to/custom_hub_name.txt --type UCSCTrackHubConnection
+
+# add a custom connection type with extra config
+$ jbrowse add-connection https://mysite.com/path/to/custom --type custom --config '{"uri":{"url":"https://mysite.com/path/to/custom"}, "locationType": "UriLocation"}' -a hg19
+
+# set an explicit id/name and write to a specific config file
 $ jbrowse add-connection https://mysite.com/path/to/hub.txt --connectionId newId --name newName --target /path/to/jb2/installation/config.json
 ```
 
 
 ## jbrowse add-track-json
 
-```
-Add a track configuration directly from a JSON hunk to the JBrowse 2 configuration
+```text
+Add a track configuration directly from a JSON hunk to the JBrowse 2
+configuration
 
 Usage: jbrowse add-track-json <track> [options]
 
 Options:
-  -h, --help                 
+  -h, --help                 Show help
 
   -u, --update               Update the contents of an existing track, matched
                              based on trackId
@@ -566,44 +904,74 @@ Options:
 
       --out                  Synonym for target
 
+Notes:
+
+The track argument is a JSON file, inline JSON, or "-" to read the JSON from
+stdin, so a track config can be generated and piped straight in.
+
+Examples:
+
+# add a track from a JSON file
 $ jbrowse add-track-json track.json
+
+# update an existing track (matched by trackId) with new JSON contents
 $ jbrowse add-track-json track.json --update
+
+# pass the track config inline instead of via a file
+$ jbrowse add-track-json '{"type":"FeatureTrack","trackId":"genes","assemblyNames":["hg38"],"adapter":{"type":"Gff3TabixAdapter","gffGzLocation":{"uri":"genes.gff.gz"}}}'
+
+# pipe the track config in from another program
+$ jq '.tracks[0]' other/config.json | jbrowse add-track-json -
+
+# write to a config.json in a specific installation directory
+$ jbrowse add-track-json track.json --out /path/to/jb2/
 ```
 
 
 ## jbrowse remove-track
 
-```
-Remove a track configuration from a JBrowse 2 configuration. Be aware that this can cause crashes in saved sessions that refer to this track!
+```text
+Remove a track configuration from a JBrowse 2 configuration. Be aware that this
+can cause crashes in saved sessions that refer to this track!
 
 Usage: jbrowse remove-track <trackId> [options]
 
 Options:
-  -h, --help                 
+  -h, --help                 Show help
 
       --target               Path to config file in JB2 installation directory
                              to write out to
 
       --out                  Synonym for target
 
-$ jbrowse remove-track trackId
+Examples:
+
+# remove a track from the config.json in the current directory
+$ jbrowse remove-track my_track_id
+
+# remove a track from a config.json in a specific installation directory
+$ jbrowse remove-track my_track_id --out /path/to/jb2/
+
+# remove a track from a specific config file
+$ jbrowse remove-track my_track_id --target /path/to/jb2/config.json
 ```
 
 
 ## jbrowse set-default-session
 
-```
+```text
 Set a default session with views and tracks
 
-Usage: jbrowse add-track <track> [options]
+Usage: jbrowse set-default-session [options]
 
 Options:
   -s, --session              set path to a file containing session in json
-                             format (required, unless using
-                             delete/currentSession flags)
+                             format, or "-" to read it from stdin (required,
+                             unless using delete/currentSession flags)
 
-  -n, --name                 Give a name for the default session [default: New
-                             Default Session]
+  -n, --name                 Give a name for the default session (overrides any
+                             name in the session file; defaults to "New Default
+                             Session")
 
   -c, --currentSession       List out the current default session
 
@@ -616,14 +984,25 @@ Options:
 
   -h, --help                 Show help
 
+Examples:
+
 # set default session for the config.json in your current directory
 $ jbrowse set-default-session --session /path/to/default/session.json
 
 # make session.json the defaultSession on the specified target config.json file
 $ jbrowse set-default-session --target /path/to/jb2/installation/config.json --session session.json
 
-# print current default session
-$ jbrowse set-default-session --currentSession # Prints out current default session
+# override the name stored in the session file
+$ jbrowse set-default-session --session session.json --name "My default view"
+
+# pipe a session in from another program
+$ jq '.defaultSession' other/config.json | jbrowse set-default-session --session -
+
+# print the current default session
+$ jbrowse set-default-session --currentSession
+
+# remove the existing default session
+$ jbrowse set-default-session --delete
 ```