README.md
1# cloak
2
3A Command Line OTP (One Time Password) Authenticator application written in Rust that generates
4time-based and counter-based OTP codes.
5
6[](https://travis-ci.com/evansmurithi/cloak)
7[](https://ci.appveyor.com/project/evansmurithi/cloak)
8
9[](https://crates.io/crates/cloak)
10
11## Motivation
12
13- [Why you shouldn’t scan two-factor authentication QR codes!](https://medium.com/crypto-punks/why-you-shouldnt-scan-two-factor-authentication-qr-codes-e2a44876a524)
14- As a means of learning the Rust programming language.
15- Easier to copy the OTP code from my terminal to the login form, rather than from
16my phone to my laptop.
17
18## Example
19
20<p align="center">
21 <img src="https://cdn.rawgit.com/evansmurithi/cloak/6d113aa8376b04cce12b64261962750532997e64/assets/cloak_example.svg">
22</p>
23
24## Installation
25
26To install `cloak`, you can do either of the following:
27
281. **Binaries**
29
30 You can download the binaries [here](https://github.com/evansmurithi/cloak/releases).
31 Make sure to put the path to the binary into your `PATH`.
32
332. **Crates.io**
34
35 Once you've installed Rust, install `cloak` by typing the following in the terminal:
36
37 ```bash
38 cargo install cloak
39 ```
40
41 This will download and compile `cloak`. After this is finished, add the Cargo
42 bin directory to your `PATH`.
43
44## Usage
45
46The sub-commands included in `cloak` are as follows:
47
48```bash
49$ cloak -h
50cloak 0.1.0
51Evans Murithi <murithievans80@gmail.com>
52A Command Line OTP Authenticator application.
53
54USAGE:
55 cloak [SUBCOMMAND]
56
57FLAGS:
58 -h, --help Prints help information
59 -V, --version Prints version information
60
61SUBCOMMANDS:
62 add Add a new account
63 delete Delete an account
64 help Prints this message or the help of the given subcommand(s)
65 list List OTP for all accounts
66 recovery_codes View recovery codes for an account
67 view View the OTP for an account
68```
69
70To view the help of any of the subcommands below, add `-h` or `--help`, e.g. `cloak add -h`.
71
72- `cloak add <account> <key>`
73
74 This will add a new account. You will need to provide the name of the account
75 as well as valid base32 encoded key. Example:
76
77 ```bash
78 $ cloak add github 4AZJFQFIGYM2KMTOO72I6FAOZ6ZFWJR6
79 ```
80
81- `cloak view <account>`
82
83 This will print the TOTP/HOTP of the account you want to view. Example:
84
85 ```bash
86 $ cloak view github
87 123456
88 ```
89
90- `cloak list`
91
92 This prints all the accounts with their respective TOTP/HOTP codes. Example:
93
94 ```bash
95 $ cloak list
96 Account: github
97 TOTP: 607091
98
99 Account: gitlab
100 TOTP: 325414
101 ```
102
103- `cloak delete <account>`
104
105 This will delete an account. Once deleted, you cannot view the OTP codes for
106 the account. Example:
107
108 ```bash
109 $ cloak delete github
110 Account successfully deleted
111 $ cloak view github
112 Account with the name 'github' does not exist. Consider adding it.
113 ```
114
115- `cloak recovery_codes <account>`
116
117 This will open a file, using your preferred editor, to either save new recovery
118 codes or view existing recovery codes.
119
120## Contributions
121
122If you want to contribute to `cloak` you will have to clone the repository on your
123local machine:
124
125```bash
126$ git clone https://github.com/evansmurithi/cloak.git
127```
128
129To build, `cd` into `cloak/` and run:
130
131```bash
132$ cargo build
133```
134
135To run tests:
136
137```bash
138$ cargo test
139```
140
){kind=link}
){kind=link}
){kind=link}
