Download the 10x Genomics Cloud CLI for your operating system and unpack it to a convenient location. Your home directory is a good default location. Optionally, install the binary in a location where you can execute it globally (e.g., /usr/local/bin).

Copy
curl -f -o txg-linux-v4.0.0.tar.gz https://cf.10xgenomics.com/cloud-cli/v4.0.0/txg-linux-v4.0.0.tar.gz

and then to unpack:

Copy
tar -zxvf txg-linux-v4.0.0.tar.gz

Below is a step-by-step video guide which demonstrates how to install and run commands in the 10x Genomics Cloud CLI for macOS operating systems. The video follows the option 1 method for running Cloud CLI commands. Linux users will find the installation and usage instructions nearly identical to macOS users.

To run the 10x Genomics Cloud CLI, you need to enter the path to the executable.

Option 1: You can navigate into the executable's directory, for example txg-linux-v4.0.0, and run the command from within the directory every time you want to run a command. For example:

Copy
cd /home/user.name/apps/txg-linux-v4.0.0/
./txg help

Option 2: Or you can specify the full path to the executable every time you want to run a command. For example:

Copy
/home/user.name/apps/txg-linux-v4.0.0/txg help

Option 3: Or you can add the txg executable to your $PATH. This means you can type txg [command] from anywhere to access the executable and run commands. If you use the echo command below, you should see a list of directories separated by colons similar to below.

Copy
echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/go/bin

If you put the 10x Genomics Cloud CLI executable in one of these directories, you've added it to your $PATH and can run the txg command from anywhere. There are several ways to add an executable to your $PATH. Here's one method:

First, navigate into the directory you just downloaded and unpacked.

Copy
cd txg-linux-v4.0.0/

Then print the path to current directory using this command:

Copy
pwd

The output should be the directory containing the txg executable. Copy the outputted path and use it in the following export command to add it into the $PATH variable.

Copy
export PATH=[directory containing the executable]:$PATH

For example:

Copy
export PATH=/mnt/home/user.name/yard/apps/txg-linux-v4.0.0:$PATH

To verify you correctly added the 10x Genomics Cloud CLI to your $PATH, enter:

Copy
which txg

You should see output similar to the following:

Copy
/mnt/home/user.name/yard/apps/txg-linux-v4.0.0/txg

Note: this only temporarily adds the executable to your $PATH. It is only valid in the current shell session. To permanently add txg to your $PATH, add the export command you just used to your .bashrc (Linux) or .zshrc (macOS v10.15+), which is a special script that runs everytime you login to your system. For more details, view this tutorial.

Use txg --help to read about the available commands, subcommands, and their respective flag options. The top level of cloud CLI commands are shown in the table below:

To navigate the subcommand help text, you can run txg analyses -h, txg analyses create -h, and so forth, with each available subcommand. For example, the following are the subcommands of the txg analyses command.

The 10x Genomics Cloud CLI supports a number of flags for every command.

txg auth [command]

txg files upload --project-id PROJECT-ID [insert path to input files]

Upload input files to a project in your account. For detailed instructions, view our tutorial here.

txg files list PROJECT-ID

List input files for the specified project ID. You can find the ID of a project by running txg projects list.

There are two primary ways to create analyses:

• Single-Step Upload and Analysis: Upload your FASTQ files and set up your analysis simultaneously by running analyses create cellranger or the cellranger command (similarly for cellranger-arc and spaceranger). These are command aliases, however the analyses create option provides additional cloud analysis management subcommands. If any specified files or references do not exist in 10x Cloud, the application will upload them as needed before starting the analysis.
• Separate Upload and Analysis: Upload your FASTQ files first using the upload command or the UI, then separately initiate the analysis with the create command. For this method, you can refer to pre-uploaded files in 10x Cloud by using the txg://fastqs/<filename> or txg://fastqs/<file_uuid> designation.

You can specify files from either your local system or 10x Cloud:

• 10x Cloud Files: Designate files already in 10x Cloud with txg://<file_type>/<filename>. Accepted file types include fastqs and references. For example:
  • txg://fastqs/3p_gex_S1_L001
  • txg://references/custom_reference_data
  • txg://references/feature_reference.csv
  • txg://references/probe-set_reference.csv
• Local System Files: Provide the full path to the file(s) on your system (e.g., ~/local_path_to/<filename>).

Example cellranger count pipeline analysis set up:

Copy
txg analyses create cellranger count --analysis-name CLI-test-count-3pgex \
  --product-version latest \
  --project-name testproject \
  --fastqs txg://fastqs/3p_gex_S1_L001 \
  # Use a pre-built reference
  --transcriptome refdata-gex-GRCh38-2024-A
  # Alternatively, you can specify custom ref e.g., as:
  #--transcriptome txg://references/<custom reference name or uuid>

Or

Copy
txg cellranger count --analysis-name CLI-test-count-3pgex \
  --product-version latest \
  --project-name testproject \
  --fastqs txg://fastqs/3p_gex_S1_L001 \
  --transcriptome refdata-gex-GRCh38-2024-A

Example cellranger multi pipeline analysis set up:

Copy
txg analyses create cellranger multi --analysis-name testrun1 \
    --csv ~/path_to_csv/multi_config.csv \
    --project-name testproject \
    --product-version latest

Or

Copy
txg cellranger multi --analysis-name testrun1 \
    --csv ~/path_to_csv/multi_config.csv \
    --project-name testproject \
    --product-version latest

For Cell Ranger multi pipeline analyses, the multi config CSV file format is the same as Cell Ranger pipeline runs, with the added feature of referring to pre-uploaded files using the txg:// notation. Here are two examples including the cloud txg notation for files uploaded to the 10x Cloud:

• A single 3' Gene Expression library analysis using a custom reference transcriptome. The output will include BAM files and automated cell type annotation results.

  Copy
  [gene-expression]
  reference,txg://references/<your custom reference name or uuid>
  create-bam,true
  cell-annotation-model,auto
  
  [libraries]
  fastq_id,fastqs,feature_types
  3p_gex,txg://fastqs/3p_gex_S1_L001,Gene Expression
  

• A Flex Gene Expression and CRISPR Guide Capture library analysis using the pre-built GRCh38-2024-A human transcriptome reference. The probe set, feature reference, and input FASTQ files are already uploaded to the 10x Cloud, so we can refer to them with txg notation. The output in this example will not include BAM files.

  Copy
  [gene-expression]
  ref,refdata-cellranger-GRCh38-2024-A
  probe-set,txg://references/probe-set_reference.csv
  create-bam,false
  
  [feature]
  ref,txg://references/feature_reference.csv
  
  [libraries]
  fastq_id,fastqs,lanes,feature_types
  crispr_fastq,txg://fastqs/crispr_S1_L001,any,CRISPR Guide Capture
  gex_fastq,txg://fastqs/gex_S1_L001,any,Gene Expression
  
  [samples]
  sample_id,probe_barcode_ids
  sample1,BC001+CR001|BC002+CR002|BC003+CR003|BC004+CR004
  sample2,BC005+CR005|BC006+CR006|BC007+CR007|BC008+CR008
  sample3,BC009+CR009|BC010+CR010|BC011+CR011|BC012+CR012
  sample4,BC013+CR013|BC014+CR014|BC015+CR015|BC016+CR016
  

You can use the CLI to batch multiple analyses at once. This should be run as a bash script, i.e., the commands should be put in a <filename>.sh file and executed via .<filename>.sh.

For example:

Copy
txg cellranger multi --csv ~/path_to/multi-config1.csv --project-name project1 --product-version latest --analysis-name test1 --assumeyes --wait-completion=false &
txg cellranger multi --csv ~/path_to/multi-config2.csv --project-name project1 --product-version latest --analysis-name test2 --assumeyes --wait-completion=false &
txg cellranger multi --csv ~/path_to/multi-config3.csv --project-name project1 --product-version latest --analysis-name test3 --assumeyes --wait-completion=false

To avoid interruptions, you can set the --accept-payment and --assumeyes flags.

txg analyses download ANALYSIS-ID [flags]

Download output files from the specified analysis. If --file-id is not present, all non-expired output files will be downloaded. If --file-id is present, only the specified files will be downloaded.

By default, the files will be downloaded into the directory from which the command is run (typically the path/to/txg/ directory). To download to an alternate location, specify a file path using the --target-dir argument.

At this time, only free file downloads are supported via the 10x Genomics Cloud CLI. Any downloads beyond the free quota must be initiated via curl, wget, or download in the web browser.

txg analyses files ANALYSIS-ID

View a list of all non-expired output files for the specified analysis.

txg analyses list PROJECT-ID

Display a list of your completed analyses for the specified project.

txg analyses get ANALYSIS-ID

Show the details of the specified analysis. You can find the analysis ID of your analyses by running txg analyses list.

txg projects create --name NAME [--description DESC]

Create a new project with the specified name and optional description. The project name must be unique across all your projects.

txg projects list [flags]

Display a list of your projects, optionally sorted by a specific field.

txg projects update PROJECT-ID [flags]

Update the name and/or description of the specified project. A project's ID can be displayed by running txg projects list.

txg references upload [insert path to reference directory]

Upload an uncompressed or compressed reference directory. For detailed instructions on uploading reference files to a project, view our tutorial here.

txg references delete REFERENCE-ID

Delete the specified custom reference. You can find the reference ID of your references by running txg references list.

txg references get REFERENCE-ID

Show the details of the specified custom reference. You can find the reference ID of your references by running txg references list.

txg references list [FLAGS]

Display a list of your custom references, optionally sorted by a specific field.

txg references update REFERENCE-ID [FLAGS]

Update one or more metadata fields associated with your custom reference. You can find the ID of a reference by running txg references list.