# qshell: a command line front end to the Qiniu cloud API > qshell is a Go command line tool that wraps the publicly documented Qiniu APIs so a developer can upload, download, inspect buckets and run CDN and storage operations from a terminal, with local encrypted credential storage and a layered config file system. It suits developers who script against Qiniu storage, and it is a poor fit if you want a general purpose cloud CLI, since it only speaks one provider. **qiniu/qshell** — Shell Tools for Qiniu Cloud - Repository: https://github.com/qiniu/qshell - Stars: 1,021 · Forks: 199 - Language: Go - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/qiniu-qshell ## A thin wrapper over a documented public API, not a private SDK qshell is described as a command line tool built on the publicly documented Qiniu APIs, designed and developed to help developers solve problems quickly. The stated purpose is to gather the frequently used methods from Qiniu storage, CDN and the other Qiniu services into convenient commands, with b64decode given as the example, decoding the URL-safe Base64 that Qiniu uses in its own URLs. That framing places the project precisely. It is not a new protocol and not a privileged channel into the platform, it is a scripting surface over an API anyone could call directly, which is why the README invites requests for new commands in the issue list and says they will be evaluated. The project is MIT licensed and the repository is not archived, with the last push on 2026-09-11. ## Install is download and chmod, because there is nothing to build The tool is written in Go, and the README says pre-compiled binaries for the mainstream platforms are provided so that developers who do not know Go, or who just want to solve a problem, do not have to. Those binaries are bundled into a single archive and you pick the one for your platform. The tool is a command line program, so once downloaded it is used directly. On Linux and Mac, a Permission Denied error is fixed with chmod +x qshell, and to run it from anywhere you add the directory to $PATH in the shell configuration file, which is ~/.bashrc for bash and ~/.zshrc for zsh. ``` export PATH=$PATH:/home/jemy/tools ``` You then either source that file or open a new terminal. On Windows the README has a different warning, because double-clicking the executable closes the window immediately, so the tool has to be launched from a command prompt by typing its name. ## Credentials live in a local store, and the account command is the entry point The tool has two classes of command, authenticated and unauthenticated, and the authenticated ones need the AccessKey, SecretKey and Name from a Qiniu account. You record them with the account command, where Name is a string you choose that identifies the pair locally, and the tool stores the account information encrypted. ``` $ qshell account ``` There is a subtlety for anyone whose credentials start with a hyphen, because the tool would otherwise read them as command line options, and the double dash separator is the escape. ``` $ qshell account -- ``` The user subcommand manages the stored set, listing accounts, switching between them with qshell user cu , switching back to the previous one with no argument, looking one up, and deleting. The README also notes a migration detail, that accounts recorded by versions before 2.3.0 need to be cleared with qshell user clean and re-recorded, which is the kind of detail that only appears in a tool with a long history. ## Three ways to supply keys, with a documented precedence order Account management is deliberately layered, and the README gives the priority order explicitly. You can record credentials in the local database with the account command, you can set them in a configuration file passed with -C, and some subcommands accept --access-key and --secret-key directly. The order from highest to lowest is the command line, then the configuration file, then the local database lookup of the current user. In practice that means a script can override the stored keys for a single invocation without disturbing the account you normally work under, which is the behaviour you want in a CI job that runs against a different bucket set. The -L option makes the current working directory the configuration directory, and -C points at a specific configuration file. ## The config file is JSON, in two scopes, and hosts are set per service The configuration file format is JSON, in two layers. The global configuration is a .qshell.json file in the home directory and applies to every account, while the account configuration is a .qshell.json in the qshell user directory under the home path for that account, and it takes priority over the global one. You can set use_https for whether requests use HTTPS, and you can set hosts for the io, up, uc, api, rs and rsf services, with the rule that apart from uc host, the others must either all be configured or none. The public cloud needs no host configuration, and for a private cloud, if it supports the uc bucket region query you only need to set uc host, otherwise you must set all of them. ```json { "use_https": false, "hosts": { "rs": "rs-test.qiniu.com", "io": "io-test.qiniu.com", "uc": "uc-test.qiniu.com", "api": "api-test.qiniu.com", "up": "up-test.qiniu.com", "rsf": "rsf-test.qiniu.com" } } ``` The same precedence logic applies when a command's own settings overlap the file, and the README states the order as command configuration, then account configuration, then global configuration. ## The command set is documented in the tool itself Since version 2.7.0 the command list and detailed usage documentation ship inside the tool, and the README says the documentation is self-service. qshell -h prints the list of supported commands, qshell --doc prints the detailed usage for one command, and qshell -v prints the version, which the README asks you to include when reporting a problem. The global options are a small set, with --doc for the manual, -d and -D for normal and more verbose debug logging, -h for the command list, -v for the version, -C for the configuration file and -L to use the working directory as the configuration directory. The README also documents a behavioural wrinkle worth knowing, that versions 2.7.0 through 2.9.2 did not support cancelling the expiry configuration, so an expiry of zero days deleted files immediately, and that from 2.10.0 an expiry of zero days removes the expiry instead. ## Prebuilt binaries cover a long tail of architectures The Makefile is where the packaging story becomes clear, and the list of targets is the notable part. Beyond darwin for x64 and arm64 and windows for x86, x64, arm and arm64, the linux target covers x86, x64, arm, arm64, mips, mipsle, mips64, mips64le, loong64 and riscv64, with the names built as qshell-$(VERSION)-linux-. The builds set CGO_ENABLED=0 for the Linux targets and pass linker flags that inject the version into the binary and build statically. The default target is all, which runs linux, windows and darwin, and the module path is github.com/qiniu/qshell/v2, so the version 2 is part of the import path. The Go dependencies show the shape of the tool, with the Qiniu Go SDK at v7, cobra for the command structure, viper for configuration, beego as the server framework, the Alibaba Cloud and AWS SDKs alongside, goleveldb for the local credential store, and a progress bar library for transfers. ## Conclusion qshell fits a developer who already stores objects in Qiniu and wants repeatable upload, download and bucket operations in a script or a CI step, since the command set mirrors the documented API and credentials can live in one encrypted local store with per-account switching. It is a poor fit if you need a multi-cloud CLI, since the whole tool is built around one provider's endpoints, and a poor fit for a private deployment whose bucket lookup does not support the uc query, because the host configuration then has to be set completely and correctly by hand. Verify first which of your buckets are discoverable through the uc host, since the README explains that configuring only the uc host works only when the private cloud can answer the bucket region query, and check your account credentials are in the form the account command expects before you script anything. ## FAQ ### How do I install qshell? Download the archive of prebuilt binaries from the releases page and pick the binary for your platform, since the tool is a command line program that is used directly with no build step. On Linux and Mac you may need chmod +x qshell if you get a Permission Denied error. ### How do I add a Qiniu account to qshell? Run qshell account with your AccessKey, SecretKey and a Name you choose, and the tool stores that account encrypted locally. If any of the values starts with a hyphen, put a double dash before them so they are not read as options. Use the qshell user subcommand to list, switch or delete accounts. ### How do I point qshell at a private cloud deployment? In a .qshell.json configuration file you set the hosts for the io, up, uc, api, rs and rsf services. If your private cloud supports the uc bucket region query you only need to configure uc host, otherwise all of the hosts must be set. ### Does qshell support shell completion? Yes. On Linux with bash you source the output of qshell completion bash, and on Mac with zsh you add a conditional block sourcing qshell completion zsh to your .zshrc. The README also notes that CentOS needs the bash-completion package installed first. ## Sources - [Issues](https://github.com/qiniu/qshell/issues) - [License: MIT](https://github.com/qiniu/qshell/blob/master/LICENSE) - [qiniu/qshell on GitHub](https://github.com/qiniu/qshell) - [README](https://github.com/qiniu/qshell/blob/master/README.md) - [Releases](https://github.com/qiniu/qshell/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qiniu-qshell