[](https://gitlab.com/d-e-s-o/nitrocli/commits/master)
[](https://crates.io/crates/nitrocli)
[](https://blog.rust-lang.org/2019/12/19/Rust-1.40.0.html)
nitrocli
========
- [Changelog](CHANGELOG.md)
**nitrocli** is a program that provides a command line interface for
interaction with [Nitrokey Pro][nitrokey-pro] and [Nitrokey
Storage][nitrokey-storage] devices.
The following commands are currently supported:
- list: List all attached Nitrokey devices.
- status: Report status information about the Nitrokey.
- lock: Lock the Nitrokey.
- config: Access the Nitrokey's configuration
- get: Read the current configuration.
- set: Change the configuration.
- encrypted: Work with the Nitrokey Storage's encrypted volume.
- open: Open the encrypted volume. The user PIN needs to be entered.
- close: Close the encrypted volume.
- hidden: Work with the Nitrokey Storage's hidden volume.
- create: Create a hidden volume.
- open: Open a hidden volume with a password.
- close: Close a hidden volume.
- otp: Access one-time passwords (OTP).
- get: Generate a one-time password.
- set: Set an OTP slot.
- status: List all OTP slots.
- clear: Delete an OTP slot.
- pin: Manage the Nitrokey's PINs.
- clear: Remove the user and admin PIN from gpg-agent's cache.
- set: Change the admin or the user PIN.
- unblock: Unblock and reset the user PIN.
- pws: Access the password safe (PWS).
- get: Query the data on a PWS slot.
- set: Set the data on a PWS slot.
- status: List all PWS slots.
- clear: Delete a PWS slot.
- unencrypted: Work with the Nitrokey Storage's unencrypted volume.
- set: Change the read-write mode of the unencrypted volume.
Usage
-----
Usage is as simple as providing the name of the respective command as a
parameter (note that some commands are organized through subcommands,
which are required as well), e.g.:
```bash
# Open the nitrokey's encrypted volume.
$ nitrocli storage open
$ nitrocli status
Status:
model: Storage
serial number: 0x00053141
firmware version: 0.47
user retry count: 3
admin retry count: 3
Storage:
SD card ID: 0x05dcad1d
firmware: unlocked
storage keys: created
volumes:
unencrypted: active
encrypted: active
hidden: inactive
# Close it again.
$ nitrocli storage close
```
More examples, a more detailed explanation of the purpose, the potential
subcommands, as well as the parameters of each command are provided in
the [`man` page](doc/nitrocli.1.pdf).
Installation
------------
In addition to Rust itself and Cargo, its package management tool, the
following dependencies are required:
- **hidapi**: In order to provide USB access this library is used.
- **GnuPG**: The `gpg-connect-agent` program allows the user to enter
PINs.
#### Via Packages
Packages are available for:
- Arch Linux: [`nitrocli`][nitrocli-arch] in the Arch User Repository
- Debian: [`nitrocli`][nitrocli-debian] (since Debian Buster)
- Gentoo Linux: [`app-crypt/nitrocli`][nitrocli-gentoo] ebuild
- Ubuntu: [`nitrocli`][nitrocli-ubuntu] (since Ubuntu 19.04)
#### From Crates.io
**nitrocli** is [published][nitrocli-cratesio] on crates.io and can
directly be installed from there:
```bash
$ cargo install nitrocli --root=$PWD/nitrocli
```
#### From Source
After cloning the repository the build is as simple as running:
```bash
$ cargo build --release
```
It is recommended that the resulting executable be installed in a
directory accessible via the `PATH` environment variable.
#### Bash Completion
**nitrocli** comes with Bash completion support for options and
arguments to them. A completion script can be generated via the
`shell-complete` utility program and then only needs to be sourced to
make the current shell provide context-sensitive tab completion support.
```bash
$ cargo run --bin=shell-complete > nitrocli.bash
$ source nitrocli.bash
```
The generated completion script can be installed system-wide as usual
and sourced through Bash initialization files, such as `~/.bashrc`.
Known Problems
--------------
- Due to a problem with the default `hidapi` version on macOS, users are
advised to build and install [`libnitrokey`][] from source and then
set the `USE_SYSTEM_LIBNITROKEY` environment variable when building
`nitrocli` using one of the methods described above.
- `nitrocli` cannot connect to a Nitrokey device that is currently being
accessed by `nitrokey-app` ([upstream issue][libnitrokey#32]). To
prevent this problem, quit `nitrokey-app` before using `nitrocli`.
- Applications using the Nitrokey device (such as `nitrocli` or
`nitrokey-app`) cannot easily share access with an instance of GnuPG
running shortly afterwards ([upstream issue][libnitrokey#137]).
Contributing
------------
Contributions are generally welcome. Please follow the guidelines
outlined in [CONTRIBUTING.md](doc/CONTRIBUTING.md).
Acknowledgments
---------------
Robin Krahl ([@robinkrahl](https://github.com/robinkrahl)) has been
a crucial help for the development of **nitrocli**.
The [Nitrokey UG][nitrokey-ug] has generously provided the necessary
hardware for developing and testing the program.
License
-------
**nitrocli** is made available under the terms of the
[GPLv3][gplv3-tldr].
See the [LICENSE](LICENSE) file that accompanies this distribution for
the full text of the license.
[`libnitrokey`]: https://github.com/nitrokey/libnitrokey
[nitrokey-ug]: https://www.nitrokey.com
[nitrokey-pro]: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3
[nitrokey-storage]: https://shop.nitrokey.com/shop/product/nitrokey-storage-2-56
[nitrocli-arch]: https://aur.archlinux.org/packages/nitrocli
[nitrocli-cratesio]: https://crates.io/crates/nitrocli
[nitrocli-debian]: https://packages.debian.org/stable/nitrocli
[nitrocli-gentoo]: https://packages.gentoo.org/packages/app-crypt/nitrocli
[nitrocli-ubuntu]: https://packages.ubuntu.com/search?keywords=nitrocli
[gplv3-tldr]: https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3)
[libnitrokey#32]: https://github.com/Nitrokey/libnitrokey/issues/32
[libnitrokey#137]: https://github.com/Nitrokey/libnitrokey/issues/137