{"id":20253520,"url":"https://github.com/chanzuckerberg/czid-cli","last_synced_at":"2026-03-10T23:37:15.222Z","repository":{"id":43316372,"uuid":"341320502","full_name":"chanzuckerberg/czid-cli","owner":"chanzuckerberg","description":"CZID (formerly IDseq) infectious disease command-line interface ","archived":false,"fork":false,"pushed_at":"2024-07-22T16:42:17.000Z","size":7692,"stargazers_count":21,"open_issues_count":1,"forks_count":3,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-02-11T01:17:47.736Z","etag":null,"topics":["cli","genomics","idseq"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chanzuckerberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-22T19:57:24.000Z","updated_at":"2026-01-30T18:43:25.000Z","dependencies_parsed_at":"2023-02-12T06:01:28.072Z","dependency_job_id":"b50fddd3-a573-42e8-96b9-cee3b0d29c41","html_url":"https://github.com/chanzuckerberg/czid-cli","commit_stats":null,"previous_names":["chanzuckerberg/idseq-cli-v2"],"tags_count":51,"template":false,"template_full_name":null,"purl":"pkg:github/chanzuckerberg/czid-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Fczid-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Fczid-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Fczid-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Fczid-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chanzuckerberg","download_url":"https://codeload.github.com/chanzuckerberg/czid-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanzuckerberg%2Fczid-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30362123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"ssl_error","status_checked_at":"2026-03-10T21:40:59.357Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","genomics","idseq"],"created_at":"2024-11-14T10:25:17.392Z","updated_at":"2026-03-10T23:37:15.204Z","avatar_url":"https://github.com/chanzuckerberg.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CZ ID CLI\n\nThis project is under active development and in its beta phase. It should be fairly stable but there may be some issues. If you experience an issue please [let us know](https://github.com/chanzuckerberg/czid-cli/issues).\n\nA **C**ommand **L**ine **I**nterface for [CZ ID](https://czid.org/). \n\nRewrite of https://github.com/chanzuckerberg/idseq-cli.\n\n## Getting Started\n\n### Installation\n\nCurrently only binaries are available. More types of packages coming soon.\n\n#### Linux\n\nThere are lots of options to install on Linux.\n\n##### Debian Distributions (ex. Debian, Ubuntu, Linux Mint)\n\n1. Download our [latest .deb package](https://github.com/chanzuckerberg/czid-cli/releases/latest/download/czid-cli_linux_amd64.deb).\n1. (Alternatively) Download with curl: `curl -L https://github.com/chanzuckerberg/czid-cli/releases/latest/download/czid-cli_linux_amd64.deb -o czid-cli_linux_amd64.deb`\n1. Install the package: `sudo dpkg -i czid-cli_linux_amd64.deb`\n1. (Optional) Remove the package file `rm czid-cli_linux_amd64.deb`\n\n\n##### Fedora Distributions (ex. Centos, RHEL)\n\n1. Download our [latest .rpm package](https://github.com/chanzuckerberg/czid-cli/releases/latest/download/czid-cli_linux_amd64.rpm)\n1. (Alternatively) Download with curl: `curl -L https://github.com/chanzuckerberg/czid-cli/releases/latest/download/czid-cli_linux_amd64.rpm -o czid-cli_linux_amd64.rpm`\n1. Install the package: `sudo rpm -i czid-cli_linux_amd64.rpm`\n1. (Optional) Remove the package file: `rm czid-cli_linux_amd64.rpm`\n\n##### Other Linux: Install via Homebrew for Linux\n\n1. Make sure you have [Homebrew for Linux](https://docs.brew.sh/Homebrew-on-Linux)\n1. Add the chanzuckerberg tap: `brew tap chanzuckerberg/tap`\n1. Install the package: `brew install czid-cli`\n\n##### Other Linux: Without Homebrew\n\nFollow the instructions for [installing from binaries](#from-binaries).\n\n#### MacOs\n\nczid-cli is available via homebrew and natively supports Apple Silicon! (via the `darwin_arm64` binary)\n\n##### Install via Homebrew\n\n1. Make sure you have [Homebrew for Linux](https://docs.brew.sh/Homebrew-on-Linux)\n1. Add the chanzuckerberg tap: `brew tap chanzuckerberg/tap`\n1. Install the package: `brew install czid-cli`\n\n##### Without Homebrew\n\nFollow the instructions for [installing from binaries](#from-binaries).\n\n#### Windows\n\nFollow the instructions for [installing from binaries](#from-binaries).\n\n#### From Binaries\n\n1. Navigate to our [latest release](https://github.com/chanzuckerberg/czid-cli/releases/latest).\n1. Available binaries will be under the `Assets` tab as archives (`.tar.gz` for Linux + MacOS, `.zip` for Windows)\n1. Download appropriate archive for your operating system and architecture\n1. Unzip the file, the `czid` executable will be inside\n\n    Linux + MacOS: `tar -xf path/to/archive.tar.gz`\n\n    Windows: `expand-archive -path 'c:\\path\\to\\archive.zip' -destinationpath '.\\czid-cli'`\n\n1. Files with shell completions are also inside so you can move them to the appropriate place for your shell\n1. To use the binary you either need to add it to your `PATH` so you can execute it as `czid` or execute the binary directly with the path to the binary (i.e. `/path/to/czid` on Linux + MacOS or `C:\\path\\to\\czid.exe` on windows). If you are executing the binary using it's path keep in mind that you should use the path to the czid binary instead of the `czid` command every time you use it.\n\n\nNote on MacOS: Currently we don't sign our binary so you will need to manually remove the quarentine attribute from the binary: `sudo xattr -d com.apple.quarantine path/to/binary`\n\n\n### Basic Usage\n\n#### Setup\n\nFirst log in with your CZ ID account:\n\n```bash\nczid login\n```\n\nYou will be prompted to log in with your CZ ID account via the web.\n\nAccept the user agreement:\n\n```bash\nczid accept-user-agreement\n```\n\nThis will print the user agreement and prompt you for your agreement.\n\n#### Upload a Single Sample\n\nYou can use the CZ ID CLI to upload samples to upload a single sample to CZ ID. You can upload a single file for single end reads or two files for paired end reads. Supported file types: `.fastq`/`.fq`/`.fasta`/`.fa`/`.fastq.gz`/`.fq.gz`/`.fasta.gz`/`.fa.gz`.\n\nOptionally, you can create a metadata CSV file for your sample. You can skip this step and specify your metadata with command line flags. For instructions on creating this file see:\n\n- Instructions: https://czid.org/metadata/instructions\n- Metadata dictionary and supported host genomes: https://czid.org/metadata/dictionary\n- Metadata CSV template: https://czid.org/metadata/metadata_template_csv\n\nBe sure to set the sample name in the `Sample Name` column of the CSV to the same name you pass to the `upload-sample` command with `-s`/`--sample-name`. If you would like to specify your metadata entirely with `-m` flags you don't need to include a `--metadata-csv`. If you have specified all of your metadata in the metadata csv you don't need to include any `-m` flags. `-m` flags override metadata from the csv.\n\nOnce you have set up you can use the `upload-sample` command to upload your sample to CZ ID.\n\n**Illumina**\n\nLinux + MacOS:\n\n```bash\nczid metagenomics upload-sample \\\n  -p 'Project Name' \\\n  -s 'Sample Name' \\\n  --sequencing-platform Illumina \\\n  --metadata-csv your_metadata.csv \\\n  -m 'Metadata Name=Metadata Value' \\\n  your_sample_R1.fastq.gz your_sample_R2.fastq.gz\n```\n\nWindows:\n\n```Powershell\nczid metagenomics upload-sample `\n  -p \"Project Name\" `\n  -s \"Sample Name\" `\n  --sequencing-platform Illumina `\n  --metadata-csv your_metadata.csv `\n  -m \"Metadata Name=Metadata Value\" `\n  your_sample_R1.fastq.gz your_sample_R2.fastq.gz\n```\n\nNote: The sample name is optional. If it is not included it will be computed from your input file name based on the same rules as uploading multiple samples.\n\n**Nanopore**\n\nLinux + MacOS:\n\n```bash\nczid metagenomics upload-sample \\\n  --project 'Your Project ID' \\\n  --sample-name 'Your Sample Name' \\\n  --metadata-csv 'Your_metadata_file.csv' \\\n  --sequencing-platform 'Nanopore' \\\n  --guppy-basecaller-setting 'hac' \\\n  your_sample.fastq.gz\n```\n\nWindows:\n\n```Powershell\nczid metagenomics upload-sample `\n  --project \"Your Project ID\" `\n  --sample-name \"Your Sample Name\" `\n  --metadata-csv \"Your_metadata_file.csv\" `\n  --sequencing-platform \"Nanopore\" `\n  --guppy-basecaller-setting \"hac\" `\n  your_sample.fastq.gz\n```\n\n**AMR**\n\nLinux + MacOS:\n\n```bash\nczid amr upload-sample \\\n  --project 'Your Project ID' \\\n  --sample-name 'Your Sample Name' \\\n  --metadata-csv 'Your_metadata_file.csv' \\\n  your_sample.fastq.gz\n```\n\nWindows:\n\n```Powershell\nczid amr upload-sample `\n  --project \"Your Project ID\" `\n  --sample-name \"Your Sample Name\" `\n  --metadata-csv \"Your_metadata_file.csv\" `\n  your_sample.fastq.gz\n```\n\n#### Upload Multiple Samples\n\nThe CZ ID CLI can search a directory for read files and upload supported files as samples. Supported file types are: `.fastq`/`.fq`/`.fasta`/`.fa`/`.fastq.gz`/`.fq.gz`/`.fasta.gz`/`.fa.gz`. Sample names are computed based on the names of the files. Sample names the base name of the file with the extension, `_R1`, `_R2`, `_R1_001`, and `_R2_001` removed. If two files have the same sample name and one has `R1` and the other has `R2` the files will be uploaded to the same sample as paired reads. Since only the base name of the file and no parent directories are taken into account file names must be globally unique (except for the same sample's `R1` and `R2` files). Here are a few examples of sample names for various paths:\n\n- `your_directory_of_samples/my_sample.fasta` =\u003e `my_sample`\n- `your_directory_of_samples/sample_one/sample_one_R1.fastq.gz` =\u003e `sample_one`\n- `your_directory_of_samples/sample_one/sample_one_R2.fastq.gz` =\u003e `sample_one` (pair of the above example)\n- `your_directory_of_samples/some_directory/some_other_directory/sample_two_R1_001.fa.gz` =\u003e `sample_two`\n\nThis is the first pass of directory uploads and we would like to support more directory structures. If you have any suggestions for directory structure uploads [we'd love to hear from you](https://github.com/chanzuckerberg/czid-cli/issues).\n\nOptionally, you can create a metadata CSV file for your sample. You can skip this step and specify your metadata with command line flags. For instructions on creating this file see:\n\n- Instructions: https://czid.org/metadata/instructions\n- Metadata dictionary and supported host genomes: https://czid.org/metadata/dictionary\n- Metadata CSV template: https://czid.org/metadata/metadata_template_csv\n\nTo associate a row of metadata with a sample you must enter the correct sample name in the `Sample Name` column of the CSV. If you would like to specify your metadata entirely with `-m` flags you don't need to include a `--metadata-csv`. If you have specified all of your metadata in the metadata csv you don't need to include any `-m` flags. `-m` flags override metadata from the csv.\n\nOnce you have set up you can use the `upload-samples` command to upload your directory to CZ ID.\n\n**Illumina**\n\nLinux + MacOS:\n\n```bash\nczid metagenomics upload-samples \\\n  -p 'Project Name' \\\n  --sequencing-platform Illumina \\\n  --metadata-csv your_metadata.csv \\\n  -m 'Metadata Name=Metadata Value' \\\n  your_directory_of_samples\n```\n\nWindows:\n\n```Powershell\nczid metagenomics upload-samples `\n  -p \"Project Name\" `\n  --sequencing-platform Illumina `\n  --metadata-csv your_metadata.csv `\n  -m \"Metadata Name=Metadata Value\" `\n  your_directory_of_samples\n```\n\n**Nanopore**\n\nLinux + MacOS:\n\n```bash\nczid metagenomics upload-samples \\\n  --project 'Your Project ID' \\\n  --metadata-csv 'Your_metadata_file.csv' \\\n  --sequencing-platform 'Nanopore' \\\n  --guppy-basecaller-setting 'hac' \\\n  your_directory_of_samples\n```\n\nWindows:\n\n```Powershell\nczid metagenomics upload-samples `\n  --project \"Your Project ID\" `\n  --metadata-csv \"Your_metadata_file.csv\" `\n  --sequencing-platform \"Nanopore\" `\n  --guppy-basecaller-setting \"hac\" `\n  your_directory_of_samples\n```\n\n**AMR**\n\nLinux + MacOS:\n\n```bash\nczid amr upload-samples \\\n  -p 'Project Name' \\\n  --metadata-csv your_metadata.csv \\\n  -m 'Metadata Name=Metadata Value' \\\n  your_directory_of_samples\n```\n\nWindows:\n\n```Powershell\nczid amr upload-samples `\n  -p \"Project Name\" `\n  --metadata-csv your_metadata.csv `\n  -m \"Metadata Name=Metadata Value\" `\n  your_directory_of_samples\n```\n\n## Configuration\n\nczid-cli can be configured with environment variables or files. By default configurations are saved in your system's default configuration directory under a directory called `czid-cli` in a yml file called `config.yml`. You can specify a custom configuration file with the `--config` flag for any command. Some commands modify your configuration like `accept-user-agreement`. These will modify whatever configuration file you specify, or the default if none are specified. Every configuration can be set as an environment variable with the prefix `CZID_CLI_`. For example, the `secret` config can be set with the environment variable: `CZID_CLI_SECRET`.\n\n### Configuration Options\n\n- `secret`: a secret used to persistently authenticate with CZ ID. Generated by running: `czid login --persistent`\n- `accepted_user_agreement`: set to `Y` if the user has accepted the user agreement. Setting this manually means you accept the user agreement. Also set via: `czid accept-user-agreement`\n\n## Differences from version 1\n\n- Resume uploads that have been interrupted\n- Faster uploads (on systems with high bandwidth) due to multithreading\n- Distributed as a single binary for easier installation that doesn't rely on dependencies on the user's machine\n- Shell completion support\n- Structured with commands and subcommands to make room for future functionality\n- Log in in the web via your CZ ID account instead of using a static token\n- Critical bugfixes\n- Uploads without the need for user prompts\n- Supports configuration files and environment variable configuration instead of relying solely on flags\n\n## Contributing\n\nThis project is not seeking contributions at this time. It is tighly coupled to the CZ ID Web App, it's features, it's APIs, and it's development goals. Please feel free to raise issues for feature requests or bugs.\n\nThis project adheres to the Contributor Covenant [code of conduct](https://www.contributor-covenant.org/). By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.\n\n## Reporting Security Issues\n\nPlease note: If you believe you have found a security issue, please responsibly disclose by contacting us at security@czid.org.\n\nSee [SECURITY.md](SECURITY.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanzuckerberg%2Fczid-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchanzuckerberg%2Fczid-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanzuckerberg%2Fczid-cli/lists"}