{"id":42794403,"url":"https://github.com/qbicsoftware/postman-cli","last_synced_at":"2026-01-30T00:26:39.749Z","repository":{"id":37735120,"uuid":"106381305","full_name":"qbicsoftware/postman-cli","owner":"qbicsoftware","description":"A client software for dataset request and download from openBIS","archived":false,"fork":false,"pushed_at":"2024-07-23T14:08:37.000Z","size":1112,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-07-23T16:15:15.909Z","etag":null,"topics":["hacktoberfest","other"],"latest_commit_sha":null,"homepage":"","language":"Java","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/qbicsoftware.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-10T07:10:43.000Z","updated_at":"2024-07-23T14:08:02.000Z","dependencies_parsed_at":"2024-07-23T16:09:42.833Z","dependency_job_id":"9e3142d4-cb5b-42d1-b330-71bbdbfe348e","html_url":"https://github.com/qbicsoftware/postman-cli","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/qbicsoftware/postman-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbicsoftware%2Fpostman-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbicsoftware%2Fpostman-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbicsoftware%2Fpostman-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbicsoftware%2Fpostman-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qbicsoftware","download_url":"https://codeload.github.com/qbicsoftware/postman-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbicsoftware%2Fpostman-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28891438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T21:06:44.224Z","status":"ssl_error","status_checked_at":"2026-01-29T21:06:42.160Z","response_time":59,"last_error":"SSL_read: 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":["hacktoberfest","other"],"created_at":"2026-01-30T00:26:39.119Z","updated_at":"2026-01-30T00:26:39.735Z","avatar_url":"https://github.com/qbicsoftware.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n# qPostman\r\n\r\n\u003ci\u003eA Java command line tool to download datasets from QBiC.\u003c/i\u003e\r\n\r\n\r\n[![Build Maven Package](https://github.com/qbicsoftware/postman-cli/actions/workflows/build-package.yml/badge.svg)](https://github.com/qbicsoftware/postman-cli/actions/workflows/build-package.yml)\r\n[![Run Maven Tests](https://github.com/qbicsoftware/postman-cli/actions/workflows/run-tests.yml/badge.svg)](https://github.com/qbicsoftware/postman-cli/actions/workflows/run-tests.yml)\r\n[![CodeQL](https://github.com/qbicsoftware/postman-cli/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/qbicsoftware/postman-cli/actions/workflows/codeql-analysis.yml)\r\n[![release](https://img.shields.io/github/v/release/qbicsoftware/postman-cli?include_prereleases)](https://github.com/qbicsoftware/postman-cli/releases)\r\n\r\n[![license](https://img.shields.io/github/license/qbicsoftware/postman-cli)](https://github.com/qbicsoftware/postman-cli/blob/master/LICENSE)\r\n![language](https://img.shields.io/badge/language-java-blue.svg)\r\n\r\n\u003c/div\u003e\r\n\r\nClient software for downloading datasets from QBiC's data management system openBIS (https://wiki-bsse.ethz.ch/display/bis/Home).\r\n\r\nWe are making use of the V3 API of openBIS (https://wiki-bsse.ethz.ch/display/openBISDoc1605/openBIS+V3+API) in order to interact with the data management system from the command line, in order to provide a quick data retrieval on the server or cluster resources, where the download via the qPortal is impractical.\r\n\r\n## How to run\r\n\r\n### Download\r\nYou can download the compiled and executable Java binaries as JAR of postman from the GitHub release page: https://github.com/qbicsoftware/postman-cli/releases.\r\n\r\nIf you want to build from source, check out the commit of your choice and execute `mvn clean package`. We only recommend this if you are familiar with Java build systems though, as we cannot give you support here. In the normal case, the binary of a stable release is sufficient.\r\n\r\n### Requirements\r\nYou need to have **Java JRE** or **JDK** installed (**openJDK** is fine), at least version 17. And the client's host must have allowance to connect to the server, which is determined by our firewall settings. If you are unsure, if your client is allowed to connect, contact us at support@qbic.zendesk.com.\r\n\r\n### Configuration\r\n\r\nPostman uses picocli file arguments. Therefore, a config file has to be passed with the '@' prefix to its path:    \r\nExample:\r\n```bash\r\njava -jar postman.jar list -u \u003cuser\u003e \u003csample\u003e @path/to/config.txt \r\n```\r\nThe structure of the configuration file is:\r\n```text\r\n[-cliOption] [value]\r\n```\r\nFor example: To set the ApplicationServerURL to another URL we have to use: \u003ccode\u003e-as [URL]\u003c/code\u003e\r\n\r\nTo use our openBIS URL we write the following lines in the config file:  \r\n(Anything beginning with '#' is a comment)   \r\n```\r\n# Config file for postman-cli\r\n# Replace the values defined after the respective CLI parameters (e.g. -u)\r\n# with your value of choice (e.g. qbcab01 as value for -u)\r\n\r\n--suffix .txt,.fastq,.fastq.gz\r\n-u qbc001\r\n--password:env MY_PASSWORD\r\n```\r\nA default file is provided here: [default-config](https://github.com/qbicsoftware/postman-cli/blob/development/config.txt).\r\n\r\n## How to use\r\n\r\n### Options\r\nJust execute the following command to get an overview of the available options. \r\n```bash \r\njava -jar postman-cli.jar -h\r\n\r\nUsage: postman-cli [-hV] COMMAND\r\n\r\nDescription:\r\nA software client for downloading data from QBiC.\r\n\r\nOptions:\r\n  -h, --help      Show this help message and exit.\r\n  -V, --version   Print version information and exit.\r\n\r\nCommands:\r\n  download  Download data from QBiC.\r\n  list      lists all the datasets found for the given identifiers\r\n\r\nOptional: specify a config file by running postman with '@/path/to/config.txt'.\r\nA detailed documentation can be found at\r\nhttps://github.com/qbicsoftware/postman-cli#readme.\r\n``` \r\n### Printed file sizes\r\nFile sizes printed by postman Kilobyte, Megabyte, Gigabyte, Terabyte and Petabyte use base 2.\r\n\r\n### How to specify your log directory\r\nBy default, postman will create log files in a directory `./logs/` in your working directory.\r\nYou can specify where logs are written by setting the system property `log.path` to the desired directory.\r\n\r\n### How to provide your credentials\r\nAfter gaining access by applying through support@qbic.zendesk.com, you can log in using your credentials.\r\nThe username is provided by us or if you have a uni-tuebingen account by the university of Tuebingen.\r\n\r\n**Provide your username:**\r\n\r\nUse the option `-u / --user` to provide us with your username.\r\n\r\n**Provide your password:**\r\n\r\nPlease never send your password over email. We will never ask you for it!\u003cbr\u003e\r\nWhen using the application, you can either:\r\n1. enter your password interactively `--password`. Do not enter your password in the command but wait for postman to ask it interactively!\r\n```bash\r\njava -jar -u qbc001a --password @path/to/config.txt \r\n```\r\n3. enter the name of a system property containing your password `--password:prop my.awesome.property`\r\n```bash\r\njava -jar -Dmy.awesome.property=ABCDEFG postman.jar -u qbc001a --password:prop my.awesome.property @path/to/config.txt \r\n```\r\n3. enter the name of an environment variable containing your password `--password:env MY_PASSWORD`. Make sure to *not* use the `$` sign before the environment variable (as in bash variables) otherwise the password is not recognized (`--password:env $MY_PASSWORD` will fail)\r\n```bash\r\nMY_PASSWORD=ABCDEFG java -jar postman.jar -u qbc001a --password:env MY_PASSWORD @path/to/config.txt \r\n```\r\n### How to provide QBiC identifiers\r\nTo specify which data you want to list or download, you need to provide us with QBiC identifiers. \r\nA QBiC project identifier begins with `Q` followed by four characters (`QTEST`). QBiC sample identifiers contain their project identifier.\r\nYou can provide identifiers either using the command line directly:\r\n```bash\r\njava -jar postman.jar QSTTSABCD01 QSTTSABCD02 QSTTSABCDE4 NGSQSTTS0012 \"QTEST*\"\r\n```\r\nPlease note: When you use the `*` character to search for all files in a project, escape your identifier using quotation marks.\r\n\r\n**Provide identifiers using a file:**\r\n\r\nYou can provide identifiers using a file containing the identifiers. Lines starting with `#` are ignored.\r\n```text\r\n# all files for the project\r\nQTEST*\r\n# all files associated with these samples\r\nQSTTS001AB\r\nQSTTS002BC\r\n```\r\n```bash\r\njava -jar postman.jar -f myids.txt @path/to/config.txt \r\n```\r\n\r\n### How to filter files by suffix\r\nBoth the `download` and the `list` command allow you to filter files by their suffix. The suffixes provided are not case-sensitive. \r\n`.TXT` and `.txt` will have the same effect.\r\nMultiple suffixes can be provided separated by a comma. A suffix does not have to be the file ending but can be any substring from the end of a file's name.\r\n\r\nIf you only want to download `fastq` and `fastq.gz` files you can run postman with \r\n```bash\r\njava -jar postman.jar -s .fastq,.fastq.gz @path/to/config.txt \r\n```\r\n\r\n### How to filter by regular expression\r\nBoth the `download` and the `list` command allow you to filter files using [a regular expression](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html). \r\nWhen filtering with a regular expression pattern, the path of the file as well as the filename are matched against the pattern. Only matching files are included in the output.\r\n\r\nIf you only want to download files containing `test` in their path or in their name, you can run postman with\r\n```bash\r\njava -jar postman.jar --pattern \".*test.*\" @path/to/config.txt \r\n```\r\nAlthough this can be used to filter for suffixes as well, please use the `--suffix` option. \r\n\r\nInstead of\r\n```bash\r\njava -jar postman.jar --pattern\".*\\.fastq\\.gz\" @path/to/config.txt \r\n```\r\ndo\r\n```bash\r\njava -jar postman.jar -s .fastq.gz @path/to/config.txt \r\n```\r\n\r\n## `list`\r\n```txt\r\nUsage: postman-cli list [-hV] [--exact-filesize] [--with-checksum]\r\n                        [--without-header] [--format=\u003cformat\u003e]\r\n                        [--pattern=\u003cregex_pattern\u003e] -u=\u003cuser\u003e [-s=\u003csuffix\u003e[,\r\n                        \u003csuffix\u003e...]]... (--password:env=\u003cenvironment-variable\u003e\r\n                        | --password:prop=\u003csystem-property\u003e | --password)\r\n                        (-f=\u003cfilePath\u003e | SAMPLE_IDENTIFIER...)\r\n\r\nDescription:\r\nlists all the datasets found for the given identifiers\r\n\r\nParameters:\r\n      SAMPLE_IDENTIFIER...   one or more QBiC sample identifiers\r\n\r\nOptions:\r\n      --password:env=\u003cenvironment-variable\u003e\r\n                             provide the name of an environment variable to\r\n                               read in your password from\r\n      --password:prop=\u003csystem-property\u003e\r\n                             provide the name of a system property to read in\r\n                               your password from\r\n      --password             please provide your password\r\n  -u, --user=\u003cuser\u003e          openBIS user name\r\n  -f, --file=\u003cfilePath\u003e      a file with line-separated list of QBiC sample ids\r\n  -s, --suffix=\u003csuffix\u003e[,\u003csuffix\u003e...]\r\n                             only include files ending with one of these\r\n                               (case-insensitive) suffixes\r\n      --pattern=\u003cregex_pattern\u003e\r\n                             only include files with paths matching this pattern\r\n      --with-checksum        list the crc32 checksum for each file\r\n      --exact-filesize       use exact byte count instead of unit suffixes:\r\n                               Byte, Kilobyte, Megabyte, Gigabyte, Terabyte and\r\n                               Petabyte\r\n      --format=\u003cformat\u003e      The format to list files in. Case-insensitive.\r\n                               Possible values: LEGACY, TSV\r\n                               Default: LEGACY\r\n      --without-header       remove the header line from the output. Only takes\r\n                               effect for tabular output formats.\r\n  -h, --help                 Show this help message and exit.\r\n  -V, --version              Print version information and exit.\r\n\r\nOptional: specify a config file by running postman with '@/path/to/config.txt'.\r\nA detailed documentation can be found at\r\nhttps://github.com/qbicsoftware/postman-cli#readme.\r\n```\r\nThe `list` command comes with some special options. You can change how your output looks by \r\n1. listing the exact number of bytes for each file `--exact-filesize`\r\n2. removing the header from the tabular output `--without-header`\r\n3. listing the crc32 checksum for every file `--with-checksum`\r\n4. specifying the output format.\r\n\r\n#### `TSV` format\r\n```text\r\nDataset\tSource\tRegistration\tSize\tFile\r\nNGSQSTTS015A0 (20211026111452695-847006)\tNGSQSTTS015A0\t2021-10-26T09:14:53.143812Z\t  1,00 B\tQSTTS015A0_awesome_genome.fastq/my_genome.fastq\r\n```\r\n```text\r\nDataset\tSource\tRegistration\tSize\tCRC32\tFile\r\nNGSQSTTS015A0 (20211026111452695-847006)\tNGSQSTTS015A0\t2021-10-26T09:14:53.143812Z\t  1,00 B\tfa0a3f23\tQSTTS015A0_awesome_genome.fastq/my_genome.fastq\r\n```\r\n\r\n#### `LEGACY` format\r\n```text\r\n# Dataset         NGSQSTTS015A0 (20211026111452695-847006)\r\n# Source          NGSQSTTS015A0\r\n# Registration    2021-10-26T09:14:53.143812Z\r\n# Size            1,00 B\r\n1,00 B\tmy_genome.fastq\r\n```\r\n```text\r\n# Dataset         NGSQSTTS015A0 (20211026111452695-847006)\r\n# Source          NGSQSTTS015A0\r\n# Registration    2021-10-26T09:14:53.143812Z\r\n# Size            1,00 B\r\n1,00 B\tfa0a3f23\tmy_genome.fastq\r\n```\r\n## `download`\r\n\r\n```txt\r\nUsage: postman-cli download [-hV] [--ignore-subdirectories] [-o=\u003coutputPath\u003e]\r\n                            [--pattern=\u003cregex_pattern\u003e] -u=\u003cuser\u003e [-s=\u003csuffix\u003e[,\r\n                            \u003csuffix\u003e...]]... (--password:\r\n                            env=\u003cenvironment-variable\u003e | --password:\r\n                            prop=\u003csystem-property\u003e | --password) (-f=\u003cfilePath\u003e\r\n                            | SAMPLE_IDENTIFIER...)\r\n\r\nDescription:\r\nDownload data from QBiC.\r\n\r\nParameters:\r\n      SAMPLE_IDENTIFIER...   one or more QBiC sample identifiers\r\n\r\nOptions:\r\n      --password:env=\u003cenvironment-variable\u003e\r\n                             provide the name of an environment variable to\r\n                               read in your password from\r\n      --password:prop=\u003csystem-property\u003e\r\n                             provide the name of a system property to read in\r\n                               your password from\r\n      --password             please provide your password\r\n  -u, --user=\u003cuser\u003e          openBIS user name\r\n  -f, --file=\u003cfilePath\u003e      a file with line-separated list of QBiC sample ids\r\n  -s, --suffix=\u003csuffix\u003e[,\u003csuffix\u003e...]\r\n                             only include files ending with one of these\r\n                               (case-insensitive) suffixes\r\n      --pattern=\u003cregex_pattern\u003e\r\n                             only include files with paths matching this pattern\r\n  -o, --output-dir=\u003coutputPath\u003e\r\n                             specify where to write the downloaded data\r\n      --ignore-subdirectories\r\n                             put all files into one directory regardless of the\r\n                               directory structure on the server; conflicts\r\n                               with files with equal names are not addressed\r\n  -h, --help                 Show this help message and exit.\r\n  -V, --version              Print version information and exit.\r\n  \r\nOptional: specify a config file by running postman with '@/path/to/config.txt'.\r\nA detailed documentation can be found at https://github.com/qbicsoftware/postman-cli#readme.\r\n```\r\nThe `download` command allows you to download data from our storage to your machine. \r\n\r\nUse the `--output-dir` option to specify a location on your client the location will be interpreted relative to your working directory.\r\n\r\nBy using the `--ignore-subdirectories` flag, you signal qpostman that you are not interested in the directory structure on the server.\r\nqpostman will thus put all files it finds into the same top-level folder.\r\n\r\n**default download behaviour**\r\n```text\r\nmy/awesome/path/file1.fastq.gz            -\u003e QABCD/my/awesome/path/file1.fastq.gz\r\nmy/awesome/other/path/file2.fastq.gz      -\u003e QABCD/my/awesome/other/path/file2.fastq.gz\r\nmy/awesome/additional/path/file3.fastq.gz -\u003e QABCD/my/awesome/additional/path/file3.fastq.gz\r\n```\r\n**with `--ignore-subdirectories`**\r\n```text\r\nmy/awesome/path/file1.fastq.gz            -\u003e QABCD/file1.fastq.gz\r\nmy/awesome/other/path/file2.fastq.gz      -\u003e QABCD/file2.fastq.gz\r\nmy/awesome/additional/path/file3.fastq.gz -\u003e QABCD/file3.fastq.gz\r\n```\r\n##### File integrity check\r\nPostman computes the CRC32 checksum for all input streams using the native Java utility class [CRC32](https://docs.oracle.com/javase/8/docs/api/java/util/zip/CRC32.html). Postman favours [`CheckedInputStream`](https://docs.oracle.com/javase/7/docs/api/java/util/zip/CheckedInputStream.html)\r\nover the traditional InputStream, and promotes the CRC checksum computation.\r\n\r\nComputed CRC32 checksums are compared with CRC32 checksums stored on our servers. \r\nWhen the checksum does not match, then the download failed. Each download is attempted multiple times. \r\nWhen all attempts fail, the mismatching checksum is recorded in your log directory in the `checksum-mismatch.log` file.\r\n\r\nThe `checksum-mismatch.log` file contains one line for each file that was not downloaded.\r\n```\r\n// values are tab separated\r\n\u003cexpected checksum\u003e \u003ccomputed checksum\u003e \u003cabsolute file path\u003e\r\n```\r\n\r\nIn addition, Postman writes the CRC32 checksum in an additional file `\u003cfile-name-of-checked-file\u003e.crc32` and stores it together with the according file.\r\n\r\n#### Advanced Options\r\n##### `postman`\r\n* `-Dlog.path`: provide the log directory\r\n* `-Dlog.level`: provide the log level to use for logging\r\n* `--source-sample-type \u003csample-type\u003e`: specify which sample type to consider as source sample type.\r\n* `--server-timeout \u003cmillis\u003e`: the server timeout in milliseconds\r\n\r\n##### `download`\r\n* `--download-attempts \u003cdownload-attempts\u003e` provide the maximal amount attempted downloads\r\n* `--buffer-size \u003cbuffer-size\u003e` provide a custom buffer size. Please only specify values that are a multiple of `1024`.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqbicsoftware%2Fpostman-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqbicsoftware%2Fpostman-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqbicsoftware%2Fpostman-cli/lists"}