The 10x Genomics Cloud CLI is a command line interface (CLI) that allows you to upload FASTQ files to projects in your 10x Genomics account, create projects from the command line, and manage other tasks related to your 10x Genomics account.
It is an executable that can be run directly and requires no compilation or installation.
Jump to:
Downloading and unpacking
Running commands
Available commands
Authentication
FASTQ file upload and management
Output file download
Projects
Reference file upload and management
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.
curl -f -o txg-linux-v1.3.1.tar.gz https://cf.10xgenomics.com/cloud-cli/v1.3.1/txg-linux-v1.3.1.tar.gz
and then to unpack:
tar -zxvf txg-linux-v1.3.1.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. 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-v1.3.1, and run the command from within the directory every time you want to run a command. For example:
cd /home/user.name/apps/txg-linux-v1.3.1/ ./txg help
Option 2: Or you can specify the full path to the executable every time you want to run a command. For example:
/home/user.name/apps/txg-linux-v1.3.1/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.
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.
cd txg-linux-v1.3.1/
Then print the path to current directory using this command:
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.
export PATH=[directory containing the executable]:$PATH
For example:
export PATH=/mnt/home/user.name/yard/apps/txg-linux-v1.3.1:$PATH
To verify you correctly added the 10x Genomics Cloud CLI to your $PATH, enter:
which txg
You should see output similar to the following:
/mnt/home/user.name/yard/apps/txg-linux-v1.3.1/txg
Note: this only temporarily adds the executable to your $PATH. It's 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.
txg [command]
[flags]
| Command | Description |
|---|---|
analyses |
Manage your analyses and download output files |
auth |
Manage authentication |
fastqs |
Upload and manage FASTQs |
help |
Help about any command |
projects |
Manage projects |
references |
Manage custom references |
The 10x Genomics Cloud CLI supports a number of flags for every command.
| Flags | Description |
|---|---|
--access-token string |
Specify an access token to use. Default: the saved token from txg auth setup. |
-H, --header header |
Extra header to include in the request when sending HTTP requests to a server. May be given multiple times to add multiple headers. Each header must be of the form 'Header: value'. Default: no extra headers. |
-h, --help |
Display help and exit. |
-q, --quiet |
Don't show progress or messages. Default: off. |
-v, --verbose |
Display extra debugging information. Default: off. |
--version |
Display version and exit. |
txg auth
[command]
| Command | Description |
|---|---|
txg auth reset |
Delete the saved access token (if it exists) |
txg auth setup |
Set up authentication. Interactively walk through the process of setting up authentication. Running this command will prompt you to visit the 10x Genomics Cloud Analysis site, copy your access token, and paste it here. The access token will then be saved locally and reused for subsequent requests. |
txg auth verify |
Verify the stored access token is valid and that the 10x Genomics Cloud Analysis service can be successfully reached. Returns a zero exit code if successful, nonzero otherwise. |
txg fastqs
upload --project-id PROJECT-ID [insert path to fastqs]
Upload FASTQ files to a project in your account. For detailed instructions on uploading FASTQ files to a project, view our tutorial here.
| Flags | Description |
|---|---|
-n, --new-project string |
Create a new project with the specified name and immediately upload the FASTQs to it. |
-p, --project-id id |
Upload the FASTQs to the project with the specified ID. The project ID is unique ID automatically created for each project. The project ID is provided in the upload command available in your project. |
txg fastqs
list PROJECT-ID
List FASTQ files for the specified project ID. You can find the ID of a project by running txg projects list.
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.
| Flags | Description |
|---|---|
--file-id string |
Comma delimited list of file IDs (optional). |
--target-dir string |
Target download directory (optional). |
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.
| Flags | Description |
|---|---|
--description string |
Project description (optional). |
--name string |
Project name (required). |
txg projects
list [flags]
Display a list of your projects, optionally sorted by a specific field.
| Flags | Description |
|---|---|
--sort-by string |
Sort the list by the specified field, which must be one of: id, name, created. Default: unsorted. |
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.
| Flags | Description |
|---|---|
--description string |
Set the project description. |
--name string |
Set the project name. |
txg references
upload [insert path to reference directory]
Upload an uncompressed or compressed reference directory. For detailed instructions on uploading FASTQ files to a project, view our tutorial here.
| Flags | Description |
|---|---|
--name string |
Specify a name for your custom reference. If not specified, the directory name will be used as the name. This can be changed after upload is completed. |
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.
| Flags | Description |
|---|---|
--sort-by string |
Sort the list by the specified field, which must be one of: id, name, or created. Default: unsorted. |
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.
| Flags | Description |
|---|---|
--build-notes string |
Specify how the custom reference was built (optional). |
--description string |
Short description (optional). |
--name string |
Set the reference name (required). |
--organism string |
Scientific name of the organism followed by the common name in parentheses (optional). |
Jump to:
Downloading and unpacking
Running commands
Available commands
Authentication
FASTQ file upload and management
Output file download
Projects
Reference file upload and management
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.
Open the Terminal app and use the command below to download:
curl -f -o txg-macos-v1.3.1.zip https://cf.10xgenomics.com/cloud-cli/v1.3.1/txg-macos-v1.3.1.zip
and then to unpack:
unzip txg-macos-v1.3.1.zip
Below is a step-by-step video guide which demonstrates how to install and run commands on the 10x Genomics Cloud CLI for macOS operating systems.
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-macos-v1.3.1, and run the command from within the directory every time you want to run a command. For example:
cd /home/user.name/apps/txg-macos-v1.3.1/ ./txg help
Option 2: Or you can specify the full path to the executable every time you want to run a command. For example:
/home/user.name/apps/txg-macos-v1.3.1/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.
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.
cd txg-macos-v1.3.1/
Then print the path to current directory using this command:
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.
export PATH=[directory containing the executable]:$PATH
For example:
export PATH=/mnt/home/user.name/yard/apps/txg-macos-v1.3.1:$PATH
To verify you correctly added the 10x Genomics Cloud CLI to your $PATH, enter:
which txg
You should see output similar to the following:
/mnt/home/user.name/yard/apps/txg-macos-v1.3.1/txg
Note: this only temporarily adds the executable to your $PATH. It's 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.
txg [command]
[flags]
| Command | Description |
|---|---|
analyses |
Manage your analyses and download output files |
auth |
Manage authentication |
fastqs |
Upload and manage FASTQs |
help |
Help about any command |
projects |
Manage projects |
references |
Manage custom references |
The 10x Genomics Cloud CLI supports a number of flags for every command.
| Flags | Description |
|---|---|
--access-token string |
Specify an access token to use. Default: the saved token from txg auth setup. |
-H, --header header |
Extra header to include in the request when sending HTTP requests to a server. May be given multiple times to add multiple headers. Each header must be of the form 'Header: value'. Default: no extra headers. |
-h, --help |
Display help and exit. |
-q, --quiet |
Don't show progress or messages. Default: off. |
-v, --verbose |
Display extra debugging information. Default: off. |
--version |
Display version and exit. |
txg auth
[command]
| Command | Description |
|---|---|
txg auth reset |
Delete the saved access token (if it exists) |
txg auth setup |
Set up authentication. Interactively walk through the process of setting up authentication. Running this command will prompt you to visit the 10x Genomics Cloud Analysis site, copy your access token, and paste it here. The access token will then be saved locally and reused for subsequent requests. |
txg auth verify |
Verify the stored access token is valid and that the 10x Genomics Cloud Analysis service can be successfully reached. Returns a zero exit code if successful, nonzero otherwise. |
txg fastqs
upload --project-id PROJECT-ID [insert path to fastqs]
Upload FASTQ files to a project in your account. For detailed instructions on uploading FASTQ files to a project, view our tutorial here.
| Flags | Description |
|---|---|
-n, --new-project string |
Create a new project with the specified name and immediately upload the FASTQs to it. |
-p, --project-id id |
Upload the FASTQs to the project with the specified ID. The project ID is unique ID automatically created for each project. The project ID is provided in the upload command available in your project. |
txg fastqs
list PROJECT-ID
List FASTQ files for the specified project ID. You can find the ID of a project by running txg projects list.
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.
| Flags | Description |
|---|---|
--file-id string |
Comma delimited list of file IDs (optional). |
--target-dir string |
Target download directory (optional). |
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.
| Flags | Description |
|---|---|
--description string |
Project description (optional). |
--name string |
Project name (required). |
txg projects
list [flags]
Display a list of your projects, optionally sorted by a specific field.
| Flags | Description |
|---|---|
--sort-by string |
Sort the list by the specified field, which must be one of: id, name, created. Default: unsorted. |
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.
| Flags | Description |
|---|---|
--description string |
Set the project description. |
--name string |
Set the project name. |
txg references
upload [insert path to reference directory]
Upload an uncompressed or compressed reference directory. For detailed instructions on uploading FASTQ files to a project, view our tutorial here.
| Flags | Description |
|---|---|
--name string |
Specify a name for your custom reference. If not specified, the directory name will be used as the name. This can be changed after upload is completed. |
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.
| Flags | Description |
|---|---|
--sort-by string |
Sort the list by the specified field, which must be one of: id, name, or created. Default: unsorted. |
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.
| Flags | Description |
|---|---|
--build-notes string |
Specify how the custom reference was built (optional). |
--description string |
Short description (optional). |
--name string |
Set the reference name (required). |
--organism string |
Scientific name of the organism followed by the common name in parentheses (optional). |
Jump to:
Downloading and unpacking
Running commands
Available commands
Authentication
FASTQ file upload and management
Output file download
Projects
Reference file upload and management
Download the 10x Genomics Cloud CLI for your operating system and unpack it to a convenient location. Your Documents folder is a good default location.
If you’re using a Windows system, download the latest version here: 10x Genomics Cloud CLI for Windows v1.3.1
Alternatively, open Command Prompt (cmd.exe) and use the command below to download:
curl -f -o txg-windows-v1.3.1.zip https://cf.10xgenomics.com/cloud-cli/v1.3.1/txg-windows-v1.3.1.zip
Below is a step-by-step video guide which demonstrates how to install and run commands in the 10x Genomics Cloud CLI for Windows operating systems.
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-windows-v1.3.1, and run the command from within the directory every time you want to run a command. For example:
cd C:/Documents/txg-windows-v1.3.1/ txg.exe help
Option 2: Or you can specify the full path to the executable every time you want to run a command. For example:
C:/Documents/txg-windows-v1.3.1/txg.exe help
Option 3: Or you can add the txg executable to your $PATH. This means you can type txg.exe [command] from anywhere to access the executable and run commands.
For instructions on adding files to $PATH on Windows, read more here.
txg.exe [command]
[flags]
| Command | Description |
|---|---|
analyses |
Manage your analyses and download output files |
auth |
Manage authentication |
fastqs |
Upload and manage FASTQs |
help |
Help about any command |
projects |
Manage projects |
references |
Manage custom references |
The 10x Genomics Cloud CLI supports a number of flags for every command.
| Flags | Description |
|---|---|
--access-token string |
Specify an access token to use. Default: the saved token from txg.exe auth setup. |
-H, --header header |
Extra header to include in the request when sending HTTP requests to a server. May be given multiple times to add multiple headers. Each header must be of the form 'Header: value'. Default: no extra headers. |
-h, --help |
Display help and exit. |
-q, --quiet |
Don't show progress or messages. Default: off. |
-v, --verbose |
Display extra debugging information. Default: off. |
--version |
Display version and exit. |
txg.exe auth
[command]
| Command | Description |
|---|---|
txg.exe auth reset |
Delete the saved access token (if it exists) |
txg.exe auth setup |
Set up authentication. Interactively walk through the process of setting up authentication. Running this command will prompt you to visit the 10x Genomics Cloud Analysis site, copy your access token, and paste it here. The access token will then be saved locally and reused for subsequent requests. |
txg.exe auth verify |
Verify the stored access token is valid and that the 10x Genomics Cloud Analysis service can be successfully reached. Returns a zero exit code if successful, nonzero otherwise. |
txg.exe fastqs
upload --project-id PROJECT-ID [insert path to fastqs]
Upload FASTQ files to a project in your account. For detailed instructions on uploading FASTQ files to a project, view our tutorial here.
| Flags | Description |
|---|---|
-n, --new-project string |
Create a new project with the specified name and immediately upload the FASTQs to it. |
-p, --project-id id |
Upload the FASTQs to the project with the specified ID. The project ID is unique ID automatically created for each project. The project ID is provided in the upload command available in your project. |
txg.exe fastqs
list PROJECT-ID
List FASTQ files for the specified project ID. You can find the ID of a project by running txg projects list.
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.
| Flags | Description |
|---|---|
--file-id string |
Comma delimited list of file IDs (optional). |
--target-dir string |
Target download directory (optional). |
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.exe 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.
| Flags | Description |
|---|---|
--description string |
Project description (optional). |
--name string |
Project name (required). |
txg.exe projects
list [flags]
Display a list of your projects, optionally sorted by a specific field.
| Flags | Description |
|---|---|
--sort-by string |
Sort the list by the specified field, which must be one of: id, name, created. Default: unsorted. |
txg.exe 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.exe projects list.
| Flags | Description |
|---|---|
--description string |
Set the project description. |
--name string |
Set the project name. |
txg.exe references
upload [insert path to reference directory]
Upload an uncompressed or compressed reference directory. For detailed instructions on uploading FASTQ files to a project, view our tutorial here.
| Flags | Description |
|---|---|
--name string |
Specify a name for your custom reference. If not specified, the directory name will be used as the name. This can be changed after upload is completed. |
txg.exe references
delete REFERENCE-ID
Delete the specified custom reference. You can find the reference ID of your references by running txg.exe 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.exe references list.
txg.exe references
list [FLAGS]
Display a list of your custom references, optionally sorted by a specific field.
| Flags | Description |
|---|---|
--sort-by string |
Sort the list by the specified field, which must be one of: id, name, or created. Default: unsorted. |
txg.exe 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.exe references list.
| Flags | Description |
|---|---|
--build-notes string |
Specify how the custom reference was built (optional). |
--description string |
Short description (optional). |
--name string |
Set the reference name (required). |
--organism string |
Scientific name of the organism followed by the common name in parentheses (optional). |