@jbrowse/cli 4.1.1 → 4.1.3

package/README.md

@@ -44,84 +44,586 @@ It is likely preferable in most cases to install the tools globally with
 `npm install @jbrowse/cli -g` however
 
 ```
+
+JBrowse CLI
+
+USAGE
+  $ jbrowse <command> [options]
+
+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
+  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
+  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
+  set-default-session  Set a default session with views and tracks
+
+OPTIONS
+  -h, --help     Show help
+  -v, --version  Show version
+
+Use "jbrowse <command> --help" for more information about a command.
+
 ```
 
 
 ## jbrowse create
 
 ```
+Downloads and installs the latest JBrowse 2 release
+
+Usage: jbrowse create [localPath] [options]
+
+Options:
+  -h, --help                 Show help
+
+  -f, --force                Overwrites existing JBrowse 2 installation if
+                             present in path
+
+  -l, --listVersions         Lists out all versions of JBrowse 2
+
+      --branch               Download a development build from a named git
+                             branch
+
+      --nightly              Download the latest development build from the main
+                             branch
+
+  -u, --url                  A direct URL to a JBrowse 2 release
+
+  -t, --tag                  Version of JBrowse 2 to install. Format is v1.0.0.
+                             Defaults to latest
+
+# Download latest release from github, and put in specific path
+$ jbrowse create /path/to/new/installation
+
+# Download latest release from github and force overwrite existing contents at path
+$ jbrowse create /path/to/new/installation --force
+
+# Download latest release from a specific URL
+$ jbrowse create /path/to/new/installation --url url.com/directjbrowselink.zip
+
+# Download a specific tag from github
+$ jbrowse create /path/to/new/installation --tag v1.0.0
+
+# List available versions
+$ jbrowse create --listVersions
 ```
 
 
 ## jbrowse add-assembly
 
 ```
+Add an assembly to a JBrowse 2 configuration
+
+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:
+                             indexedFasta, bgzipFasta, twoBit, chromSizes,
+                             custom]
+
+  -n, --name                 Name of the assembly; if not specified, will be
+                             guessed using the sequence file name
+
+  -a, --alias                An alias for the assembly name (e.g. "hg38" if the
+                             name of the assembly is "GRCh38"); can be specified
+                             multiple times
+
+      --displayName          The display name to specify for the assembly, e.g.
+                             "Homo sapiens (hg38)" while the name can be a
+                             shorter identifier like "hg38"
+
+      --faiLocation          [default: <fastaLocation>.fai] FASTA index file or
+                             URL
+
+      --gziLocation          [default: <fastaLocation>.gzi] FASTA gzip index
+                             file or URL
+
+      --refNameAliases       Reference sequence name aliases file or URL;
+                             assumed to be a tab-separated aliases file unless
+                             --refNameAliasesType is specified
+
+      --refNameAliasesType   Type of aliases defined by --refNameAliases; if
+                             "custom", --refNameAliases is either a JSON file
+                             location or inline JSON that defines a custom
+                             sequence adapter [choices: aliases, custom]
+
+      --refNameColors        A comma-separated list of color strings for the
+                             reference sequence names; will cycle through colors
+                             if there are fewer colors than sequences
+
+      --target               path to config file in JB2 installation directory
+                             to write out to. Creates ./config.json if
+                             nonexistent
+
+      --out                  synonym for target
+
+  -h, --help                 Display help for command
+
+  -l, --load                 Required flag when using a local file. Choose how
+                             to manage the data directory. Copy, symlink, or
+                             move the data directory to the JBrowse directory.
+                             Or use inPlace to modify the config without doing
+                             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
+
+      --overwrite            Overwrite existing assembly if one with the same
+                             name exists
+
+  -f, --force                Equivalent to `--skipCheck --overwrite`
+
+# 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
+
+# add assembly to a specific jb2 installation path using --out, and copies the .fa and .fa.fai file to /path/to/jb2
+$ jbrowse add-assembly GRCh38.fa --out /path/to/jb2/ --load copy
+
+# force indexedFasta for add-assembly without relying on file extension
+$ jbrowse add-assembly GRCh38.xyz --type indexedFasta --load copy
+
+# add displayName for an assembly
+$ jbrowse add-assembly myFile.fa.gz --name hg38 --displayName "Homo sapiens (hg38)"
+
+# use chrom.sizes file for assembly instead of a fasta file
+$ jbrowse add-assembly GRCh38.chrom.sizes --load inPlace
+
+# add assembly from preconfigured json file, expert option
+$ jbrowse add-assembly GRCh38.config.json --load copy
+
+# add assembly from a 2bit file, also note pointing direct to a URL so no --load flag needed
+$ 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
 ```
 
 
 ## jbrowse add-track
 
 ```
+Add a track to a JBrowse 2 configuration
+
+Usage: jbrowse add-track <track> [options]
+
+Options:
+  -h, --help                 
+
+  -t, --trackType            Type of track, by default inferred from track file
+
+  -n, --name                 Name of the track. Will be defaulted to the trackId
+                             if none specified
+
+      --indexFile            Optional index file for the track
+
+  -d, --description          Optional description of the track
+
+  -a, --assemblyNames        Assembly name or names for track as comma separated
+                             string
+
+      --category             Optional comma separated string of categories to
+                             group tracks
+
+      --config               Any extra config settings to add to a track
+
+      --target               Path to config file in JB2 installation to write
+                             out to
+
+      --out                  Synonym for target
+
+      --subDir               When using --load a file, output to a subdirectory
+                             of the target dir
+
+      --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
+
+  -f, --force                Equivalent to --skipCheck --overwrite
+
+      --protocol             Force protocol to a specific value
+
+      --bed1                 Used only for mcscan anchors/simpleAnchors types
+
+      --bed2                 Used only for mcscan anchors/simpleAnchors types
+
+# 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
+
+# copy my.bam and my.bam.bai to /path/to/jb2/bam and adds track entry to /path/to/jb2/bam/config.json
+$ jbrowse add-track my.bam --load copy --out /path/to/jb2 --subDir bam
+
+# same as above, but specify path to bai file. needed for if the bai file does not have the extension .bam.bai
+$ jbrowse add-track my.bam --indexFile my.bai --load copy
+
+# creates symlink for /path/to/my.bam and adds track to config.json
+$ jbrowse add-track /path/to/my.bam --load symlink
+
+# add track from URL to config.json, no --load flag needed
+$ 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
 ```
 
 
 ## jbrowse text-index
 
 ```
+Make a text-indexing file for any given track(s).
+
+Usage: jbrowse text-index [options]
+
+Options:
+  -h, --help                 Show CLI help
+
+      --tracks               Specific tracks to index, formatted as comma
+                             separated trackIds. If unspecified, indexes all
+                             available tracks
+
+      --excludeTracks        Specific tracks to exclude from indexing, formatted
+                             as comma separated trackIds
+
+      --target               Path to config file in JB2 installation directory
+                             to read from.
+
+      --out                  Synonym for target
+
+      --attributes           Comma separated list of attributes to index
+                             [default: Name,ID]
+
+  -a, --assemblies           Specify the assembl(ies) to create an index for. If
+                             unspecified, creates an index for each assembly in
+                             the config
+
+      --force                Overwrite previously existing indexes [default:
+                             false]
+
+  -q, --quiet                Hide the progress bars [default: false]
+
+      --perTrack             If set, creates an index per track [default: false]
+
+      --exclude              Adds gene type to list of excluded types [default:
+                             CDS,exon]
+
+      --prefixSize           Specify the prefix size for the ixx index. We
+                             attempt to automatically calculate this, but you
+                             can manually specify this too. If many genes have
+                             similar gene IDs e.g. Z000000001, Z000000002 the
+                             prefix size should be larger so that they get split
+                             into different bins
+
+      --file                 File or files to index (can be used to create trix
+                             indexes for embedded component use cases not using
+                             a config.json for example)
+
+      --fileId               Set the trackId used for the indexes generated with
+                             the --file argument
+
+      --dryrun               Just print out tracks that will be indexed by the
+                             process, without doing any indexing
+
+# indexes all tracks that it can find in the current directory's config.json
+$ jbrowse text-index
+
+# indexes specific trackIds that it can find in the current directory's config.json
+$ jbrowse text-index --tracks=track1,track2,track3
+
+# indexes all tracks except specific trackIds
+$ jbrowse text-index --exclude-tracks=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/
+
+# indexes only a specific assembly, and overwrite what was previously there using force (which is needed if a previous index already existed)
+$ jbrowse text-index -a hg19 --force
+
+# create index for some files for use in @jbrowse/react-linear-genome-view2 or similar
+$ jbrowse text-index --file myfile.gff3.gz --file myfile.vcfgz --out indexes
 ```
 
 
 ## jbrowse admin-server
 
 ```
+Start up a small admin server for JBrowse configuration
+
+Usage: jbrowse admin-server [options]
+
+Options:
+  -h, --help                 
+
+  -p, --port                 Specified port to start the server on (default:
+                             9090)
+
+      --root                 Path to the root of the JB2 installation
+
+      --bodySizeLimit        Size limit of the update message (default: 25mb)
+
+$ jbrowse admin-server
+$ jbrowse admin-server -p 8888
 ```
 
 
 ## jbrowse upgrade
 
 ```
+Upgrades JBrowse 2 to latest version
+
+Usage: jbrowse upgrade [localPath] [options]
+
+Options:
+  -h, --help                 Display help for command
+
+  -l, --listVersions         Lists out all versions of JBrowse 2
+
+  -t, --tag                  Version of JBrowse 2 to install. Format is v1.0.0.
+                             Defaults to latest
+
+      --branch               Download a development build from a named git
+                             branch
+
+      --nightly              Download the latest development build from the main
+                             branch
+
+      --clean                Removes old js,map,and LICENSE files in the
+                             installation
+
+  -u, --url                  A direct URL to a JBrowse 2 release
+
+# Upgrades current directory to latest jbrowse release
+$ jbrowse upgrade
+
+# Upgrade jbrowse instance at a specific filesystem path
+$ jbrowse upgrade /path/to/jbrowse2/installation
+
+# Upgrade to a specific tag
+$ jbrowse upgrade /path/to/jbrowse2/installation --tag v1.0.0
+
+# List versions available on github
+$ jbrowse upgrade --listVersions
+
+# Upgrade from a specific URL
+$ jbrowse upgrade --url https://sample.com/jbrowse2.zip
+
+# Get nightly release from main branch
+$ jbrowse upgrade --nightly
 ```
 
 
 ## jbrowse make-pif
 
 ```
+creates pairwise indexed PAF (PIF), with bgzip and tabix
+
+Usage: jbrowse make-pif <file> [options]
+
+Options:
+  -h, --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
+
+$ jbrowse make-pif input.paf --out output.pif.gz # specify output file, creates output.pif.gz.tbi also
 ```
 
 
 ## jbrowse sort-gff
 
 ```
+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
+
+Usage: jbrowse sort-gff [file] [options]
+
+Options:
+  -h, --help                 
+
+# sort gff and pipe to bgzip
+$ jbrowse sort-gff input.gff | bgzip > sorted.gff.gz
+$ tabix sorted.gff.gz
+
+# sort gff from stdin
+$ cat input.gff | jbrowse sort-gff | bgzip > sorted.gff.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
+
+Usage: jbrowse sort-bed [file] [options]
+
+Options:
+  -h, --help                 
+
+# sort bed and pipe to bgzip
+$ jbrowse sort-bed input.bed | bgzip > sorted.bed.gz
+$ tabix sorted.bed.gz
+
+# OR pipe data via stdin: cat file.bed | jbrowse sort-bed | bgzip > sorted.bed.gz
 ```
 
 
 ## jbrowse add-connection
 
 ```
+Add a connection to a JBrowse 2 configuration
+
+Usage: jbrowse add-connection <connectionUrlOrPath> [options]
+
+Options:
+  -h, --help                 
+
+  -t, --type                 Type of connection (e.g. JBrowse1Connection,
+                             UCSCTrackHubConnection, custom)
+
+  -a, --assemblyNames        For UCSC: optional comma separated list of assembly
+                             names to filter. For JBrowse1: a single assembly
+                             name
+
+  -c, --config               Extra config settings to add to connection in JSON
+                             object format
+
+      --connectionId         Id for the connection that must be unique to
+                             JBrowse
+
+  -n, --name                 Name of the connection. Defaults to connectionId if
+                             not provided
+
+      --target               Path to config file in JB2 installation directory
+                             to write out to
+
+      --out                  Synonym for target
+
+      --skipCheck            Don't check whether the data directory URL exists
+
+      --overwrite            Overwrites any existing connections if same
+                             connection id
+
+  -f, --force                Equivalent to --skipCheck --overwrite
+
+$ 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
+$ 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
+
+Usage: jbrowse add-track-json <track> [options]
+
+Options:
+  -h, --help                 
+
+  -u, --update               Update the contents of an existing track, matched
+                             based on trackId
+
+      --target               Path to config file in JB2 installation directory
+                             to write out to
+
+      --out                  Synonym for target
+
+$ jbrowse add-track-json track.json
+$ jbrowse add-track-json track.json --update
 ```
 
 
 ## 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!
+
+Usage: jbrowse remove-track <trackId> [options]
+
+Options:
+  -h, --help                 
+
+      --target               Path to config file in JB2 installation directory
+                             to write out to
+
+      --out                  Synonym for target
+
+$ jbrowse remove-track trackId
 ```
 
 
 ## jbrowse set-default-session
 
 ```
+Set a default session with views and tracks
+
+Usage: jbrowse add-track <track> [options]
+
+Options:
+  -s, --session              set path to a file containing session in json
+                             format (required, unless using
+                             delete/currentSession flags)
+
+  -n, --name                 Give a name for the default session [default: New
+                             Default Session]
+
+  -c, --currentSession       List out the current default session
+
+      --target               path to config file in JB2 installation directory
+                             to write out to
+
+      --out                  synonym for target
+
+      --delete               Delete any existing default session.
+
+  -h, --help                 Show help
+
+# 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
 ```