@jbrowse/cli 5.0.0-beta.1 → 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
 
@@ -59,6 +59,7 @@ COMMANDS
   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
+  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
@@ -77,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]
@@ -122,7 +123,7 @@ $ jbrowse create --listVersions
 
 ## jbrowse add-assembly
 
-```
+```text
 Add an assembly to a JBrowse 2 configuration
 
 Usage: jbrowse add-assembly <sequence> [options]
@@ -241,7 +242,7 @@ $ jbrowse add-assembly GRCh38.fa --load copy --config '{"sequence":{"formatAbout
 
 ## jbrowse add-track
 
-```
+```text
 Add a track to a JBrowse 2 configuration
 
 Usage: jbrowse add-track <track> [options]
@@ -263,9 +264,9 @@ Options:
   -a, --assemblyNames        Assembly name or names for track as comma separated
                              string. For pairwise synteny tracks the order is
                              query,target (reverse of minimap2/nucmer argument
-                             order); for all-vs-all adapters
-                             (AllVsAllPAFAdapter/AllVsAllIndexedPAFAdapter) list
-                             every assembly the file covers, in any order
+                             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
@@ -279,7 +280,7 @@ Options:
                              displayDefaults
 
       --displayDefaults      Inline JSON merged into the track displayDefaults
-                             (labels, mouseover, jexlFilters, etc.)
+                             (labels, mouseover, filter, etc.)
 
       --multiwig             Build a MultiQuantitativeTrack from several BigWigs
                              (in place of the positional track arg): a
@@ -310,6 +311,11 @@ 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,
@@ -329,7 +335,7 @@ text-index.
 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, jexlFilters).
+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,
@@ -337,11 +343,18 @@ 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 all-vs-all adapters
-(AllVsAllPAFAdapter, AllVsAllIndexedPAFAdapter) it is instead the full list of
-assemblies the file covers, in any order, since one all-vs-all file backs every
-pair.
+— 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:
 
@@ -371,12 +384,15 @@ $ 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 validate
 
-```
+```text
 Check a JBrowse configuration for errors, including the ones JBrowse itself
 accepts silently
 
@@ -397,19 +413,35 @@ nothing. That is what this command is mainly for.
 
 Two levels are reported:
 
-  error    JBrowse accepts it and silently does the wrong thing — an unknown    
-       slot, a track naming an assembly the config never defines, a           
+  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. Never fails          
- the run.
+      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
@@ -426,7 +458,7 @@ $ jbrowse validate config.json --json
 
 ## jbrowse text-index
 
-```
+```text
 Make a text-indexing file for any given track(s).
 
 Usage: jbrowse text-index [options]
@@ -499,7 +531,8 @@ 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).
+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
@@ -536,7 +569,7 @@ $ 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]
@@ -547,6 +580,9 @@ Options:
   -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)
@@ -554,9 +590,10 @@ Options:
 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 is meant for
-local configuration only: run it on a trusted machine and do not expose the port
-to untrusted networks or the public internet.
+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:
 
@@ -571,12 +608,15 @@ $ 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]
@@ -624,7 +664,7 @@ $ jbrowse upgrade --nightly
 
 ## jbrowse make-pif
 
-```
+```text
 creates pairwise indexed PAF (PIF), with bgzip and tabix
 
 Usage: jbrowse make-pif <file> [options]
@@ -637,16 +677,22 @@ Options:
 
       --csi                  Create a CSI index for the PIF file instead of TBI
 
-      --coarse               Minimum insertion/deletion length (bp) at which a
-                             coarse-tier row is split into multiple pieces so
-                             each row stays tight — 0 emits an unsplit coarse
-                             tier. Defaults to 10000. The no-CIGAR 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.
+      --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.
 
-      --no-coarse            Do not emit the coarse no-CIGAR 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:
 
@@ -666,17 +712,76 @@ $ 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
 
-# emit an unsplit coarse tier (alongside the fine tier)
-$ jbrowse make-pif input.paf --coarse 0
+# 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
 ```
+
+
+## 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
@@ -704,7 +809,7 @@ $ tabix -p gff sorted.gtf.gz
 
 ## jbrowse sort-bed
 
-```
+```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
@@ -726,7 +831,7 @@ $ tabix sorted.bed.gz
 
 ## jbrowse add-connection
 
-```
+```text
 Add a connection to a JBrowse 2 configuration
 
 Usage: jbrowse add-connection <connectionUrlOrPath> [options]
@@ -782,7 +887,7 @@ $ jbrowse add-connection https://mysite.com/path/to/hub.txt --connectionId newId
 
 ## jbrowse add-track-json
 
-```
+```text
 Add a track configuration directly from a JSON hunk to the JBrowse 2
 configuration
 
@@ -825,7 +930,7 @@ $ jbrowse add-track-json track.json --out /path/to/jb2/
 
 ## jbrowse remove-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!
 
@@ -854,7 +959,7 @@ $ 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 set-default-session [options]

package/dist/commands/add-track-utils/adapter-utils.js

@@ -1,5 +1,8 @@
 import fs from 'node:fs';
-import { adapterTypesToTrackTypeMap, formats, matchFormat, resolveIndexType, trackTypeForAdapter, } from '@jbrowse/add-track-core';
+import { adapterTypesToTrackTypeMap, formats, matchFormat, resolveIndexType, sidecarCandidateNames, trackTypeForAdapter, } from '@jbrowse/add-track-core';
+import { isURL } from '../../types/common.js';
+import { densitySidecarPath } from '../shared/density.js';
+import { configManifest } from '../validate/configManifest.generated.js';
 function hasLocField(spec) {
     return 'locField' in spec;
 }
@@ -9,24 +12,6 @@ for (const { spec } of formats) {
         adapterTypeToSpec[spec.adapterType] = spec;
     }
 }
-// What else the sidecar with this suffix can be named. `.csi` is htslib's
-// alternative for a BAI or a TBI — required for a reference over 512 Mb, and
-// written on request at any size. `stripped` is the form Picard and GATK write:
-// `reads.bai` beside `reads.bam`, where samtools writes `reads.bam.bai`.
-//
-// Per-suffix because the alternatives are: a `.crai` has no CSI form, and
-// stripping the extension off `calls.vcf.gz` would name `calls.vcf.tbi`, which
-// nothing writes. A `.fai`/`.gzi` has neither and so is absent here.
-//
-// This is `indexCandidateNames` in `@jbrowse/core/util/indexCandidates`, which
-// the add-track widget and jbrowse-img share and this CLI cannot import — it
-// carries no `@jbrowse/core` dependency, so `npm i -g @jbrowse/cli` stays a CLI
-// rather than a copy of the app. Change one, change the other.
-const ALTERNATE_SPELLINGS = {
-    '.bai': { csi: true, stripped: true },
-    '.crai': { stripped: true },
-    '.tbi': { csi: true },
-};
 /**
  * The sidecar actually sitting beside `location`, or the conventional name when
  * none of the spellings is there — so a missing index still reports the file
@@ -35,22 +20,53 @@ const ALTERNATE_SPELLINGS = {
  * Probed with `existsSync`, which is false for every candidate of a URL and so
  * leaves a remote track with exactly the conventional guess it had before this
  * existed. A remote `.csi` still wants `--indexFile`.
- *
- * The guard on the stripped spelling is load-bearing: `replace` hands back the
- * subject unchanged when the pattern does not match, so `--adapterType
- * BamAdapter` on a file named with no extension at all would offer the data
- * file as its own index — and that file certainly exists.
  */
 export function siblingSidecar(location, suffix) {
-    const { csi, stripped } = ALTERNATE_SPELLINGS[suffix] ?? {};
-    const strippedName = location.replace(/\.[^./\\]+$/, suffix);
-    const candidates = [
-        `${location}${suffix}`,
-        ...(csi ? [`${location}.csi`] : []),
-        ...(stripped && strippedName !== location ? [strippedName] : []),
-    ];
+    const candidates = sidecarCandidateNames(location, suffix);
     return candidates.find(c => fs.existsSync(c)) ?? candidates[0];
 }
+// The adapters that declare a `densityAdapter` slot, read off the generated
+// manifest `jbrowse validate` uses. The hand-written list missed `GWASAdapter`,
+// which inherits the slot through `bedTabixConfigSchema` instead of spreading
+// `densityAdapterConfigSchemaFields`, so `--density` on a Pan-UKBB file was
+// refused by a message that listed nine adapters and not the tenth.
+const densityAdapterTypes = new Set(Object.entries(configManifest.adapters)
+    .filter(([, entry]) => entry.slots.some(s => s.name === 'densityAdapter'))
+    .map(([name]) => name)
+    .sort());
+/**
+ * The adapter with its density sidecar attached, and the local file to load
+ * beside the config when there is one.
+ *
+ * An explicit `--density` is taken as given, since a URL cannot be probed;
+ * otherwise the conventional `<file>.density.bw` counts only when it is
+ * actually there, the way `siblingSidecar` probes an index.
+ */
+export function withDensityAdapter({ adapter, location, density, makeLocation, }) {
+    const supported = densityAdapterTypes.has(adapter.type);
+    if (density !== undefined && !supported) {
+        throw new Error(`--density has no slot on ${adapter.type}. The adapters carrying a density sidecar are: ${[...densityAdapterTypes].join(', ')}`);
+    }
+    const probed = location !== undefined && fs.existsSync(densitySidecarPath(location))
+        ? densitySidecarPath(location)
+        : undefined;
+    if (probed !== undefined && !supported) {
+        console.warn(`Warning: ${probed} sits beside the track file but ${adapter.type} has no densityAdapter slot, so it is not attached. The adapters carrying one are indexed: bgzip and tabix the file, then add it.`);
+    }
+    const file = density === undefined ? (supported ? probed : undefined) : density;
+    return file === undefined
+        ? { adapter }
+        : {
+            adapter: {
+                ...adapter,
+                densityAdapter: {
+                    type: 'BigWigAdapter',
+                    bigWigLocation: makeLocation(file),
+                },
+            },
+            file: isURL(file) ? undefined : file,
+        };
+}
 // builds the adapter object and the list of source files for a spec in one
 // place, so the config it writes and the files add-track copies can never drift
 function buildFromSpec(spec, { location, index, bed1, bed2, makeLocation }) {

package/dist/commands/add-track-utils/track-config.js

@@ -29,10 +29,8 @@ export function buildTrackConfig({ trackType, trackId, name, assemblyNames, cate
 // nothing was supplied, so the track omits displayDefaults entirely.
 //
 // Takes `trackType` so it can refuse a key none of that track's displays
-// declares. `--color` on an alignments track is the reachable case — that
-// display declares `colorBy`, expandTrackConfigShorthand drops the unmatched
-// key with a console warning, and the command otherwise wrote the dead setting
-// and exited 0.
+// declares: expandTrackConfigShorthand drops an unmatched key with a console
+// warning, and the command otherwise wrote the dead setting and exited 0.
 export function mergeDisplayDefaults({ configObj, color, height, displayDefaults, trackType, }) {
     const fromJson = displayDefaults
         ? parseJsonFlag(displayDefaults, '--displayDefaults')
@@ -56,9 +54,9 @@ export function mergeDisplayDefaults({ configObj, color, height, displayDefaults
 // An unknown track type accepts everything: it is a plugin's, and this manifest
 // is only the core plugins'.
 //
-// The message names the display when the track offers one — which most do, and
-// AlignmentsTrack is the case that matters here, since `--color` is the
-// reachable mistake and LinearAlignmentsDisplay is the only place to go look.
+// The message names the display where the track offers exactly one, and the
+// track otherwise: the keys checked are the union over its displays, so
+// naming one of several would send the reader to look in the wrong place.
 function checkDisplayDefaultKeys(merged, trackType) {
     const { displayTypes, keys } = displayDefaultsForTrackType(trackType);
     if (keys.length === 0) {

package/dist/commands/add-track.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { printHelp, readConfigFile, resolveConfigPath } from '../utils.js';
-import { guessTrack, guessTrackType, makeLocationProtocol, } from './add-track-utils/adapter-utils.js';
+import { guessTrack, guessTrackType, makeLocationProtocol, withDensityAdapter, } from './add-track-utils/adapter-utils.js';
 import { loadFiles } from './add-track-utils/file-operations.js';
 import { buildMultiWiggle } from './add-track-utils/multiwig.js';
 import { addSyntenyAssemblyNames, buildTrackConfig, mapLocationForFiles, mergeDisplayDefaults, } from './add-track-utils/track-config.js';
@@ -39,7 +39,7 @@ export async function run(args) {
         assemblyNames: {
             type: 'string',
             short: 'a',
-            description: 'Assembly name or names for track as comma separated string. For pairwise synteny tracks the order is query,target (reverse of minimap2/nucmer argument order); for all-vs-all adapters (AllVsAllPAFAdapter/AllVsAllIndexedPAFAdapter) list every assembly the file covers, in any order',
+            description: 'Assembly name or names for track as comma separated 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: {
             type: 'string',
@@ -59,7 +59,7 @@ export async function run(args) {
         },
         displayDefaults: {
             type: 'string',
-            description: 'Inline JSON merged into the track displayDefaults (labels, mouseover, jexlFilters, etc.)',
+            description: 'Inline JSON merged into the track displayDefaults (labels, mouseover, filter, etc.)',
         },
         multiwig: {
             type: 'string',
@@ -104,6 +104,10 @@ export async function run(args) {
             type: 'string',
             description: 'Used only for mcscan anchors/simpleAnchors types',
         },
+        density: {
+            type: 'string',
+            description: "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",
+        },
     };
     const { values: flags, positionals } = parseArgs({
         args,
@@ -128,17 +132,23 @@ export async function run(args) {
         '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, ' +
-        'jexlFilters).\n\n' +
+        'filter).\n\n' +
         '--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.\n\n' +
+        '--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.\n\n' +
         'For pairwise synteny adapters (PAF/Delta/Chain) --assemblyNames is ' +
         'query,target — the reverse of the minimap2/nucmer input order. For the ' +
-        'all-vs-all adapters (AllVsAllPAFAdapter, AllVsAllIndexedPAFAdapter) it is ' +
-        'instead the full list of assemblies the file covers, in any order, since ' +
-        'one all-vs-all file backs every pair.';
+        'multi-genome PAF adapters (MultiGenomePAFAdapter, MultiGenomeIndexedPAFAdapter) it is ' +
+        'instead the full list of assemblies the file covers, in any order.';
     const 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',
@@ -166,6 +176,9 @@ export async function run(args) {
         '',
         '# ...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',
     ];
     if (flags.help) {
         printHelp({
@@ -187,7 +200,7 @@ export async function run(args) {
     const mapLocation = (p) => wrap(mapLocationForFiles(p, load, subDir));
     // build the adapter (and the set of files to load) up front, so the track-arg
     // and load validation runs before we touch the config on disk
-    const { adapter, files, trackType, trackId } = multiwig
+    const { adapter: builtAdapter, files, trackType, trackId, } = multiwig
         ? buildMultiWiggleTrack({
             sources: multiwig,
             mapLocation,
@@ -207,6 +220,15 @@ export async function run(args) {
             trackType: flags.trackType,
             trackId: flags.trackId,
         });
+    const { adapter, file: densityFile } = withDensityAdapter({
+        adapter: builtAdapter,
+        location,
+        density: flags.density,
+        makeLocation: mapLocation,
+    });
+    if (densityFile !== undefined && !load) {
+        throw new Error(`--density names a local file (${densityFile}); pass --load to say how it is placed beside the config`);
+    }
     const baseConfigObj = config ? parseConfigFlag(config) : undefined;
     const displayDefaults = mergeDisplayDefaults({
         configObj: baseConfigObj,
@@ -245,7 +267,7 @@ export async function run(args) {
     });
     const updatedConfig = { ...configContents, tracks };
     await loadFiles({
-        files,
+        files: [...files, densityFile],
         destDir: configDir,
         mode: load,
         subDir,