Skip to content

Commit 0aae62a

Browse files
githubhjsgithubhjs
committed
Add MkDocs source + Read the Docs build config
New mkdocs-src/ (separate from docs/, which stays as the existing GitHub Pages static site at winauth.hjs.space) covers the CLI fork: quickstart, installation, full command reference (from the real --help output), and compiling. .readthedocs.yaml configures the build for Read the Docs.
1 parent 7f874c5 commit 0aae62a

8 files changed

Lines changed: 163 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,4 @@ Third Party/MetroFramework/MetroFramework.Design/bin
2121
Third Party/MetroFramework/MetroFramework.Design/obj
2222
Third Party/MetroFramework/MetroFramework/bin
2323
Third Party/MetroFramework/MetroFramework/obj
24+
site/

‎.readthedocs.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
version: 2
2+
3+
build:
4+
os: ubuntu-22.04
5+
tools:
6+
python: "3.12"
7+
8+
mkdocs:
9+
configuration: mkdocs.yml
10+
11+
python:
12+
install:
13+
- requirements: docs-requirements.txt

‎docs-requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
mkdocs==1.6.1

‎mkdocs-src/compiling.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# How to Compile
2+
3+
## Windows GUI (Visual Studio) — original WinAuth, retained for provenance
4+
5+
### Prerequisites
6+
7+
* Visual Studio 2017
8+
* Windows 8.1 SDK
9+
10+
### Installation
11+
12+
1. Install Visual Studio 2017. In the installer's component selection "Individual components", make sure to enable "Windows 8.1 SDK". See [screenshot](https://stackoverflow.com/questions/43704734/how-to-fix-the-error-windows-sdk-version-8-1-was-not-found/43888773#43888773).
13+
2. Git clone or download and extract the codebase.
14+
15+
### Building
16+
17+
1. Before starting, make sure to backup your `%AppData%\WinAuth\winauth.xml` file or export your authenticators to prevent data loss.
18+
2. Open the solution file `Net4.5\WinAuth.sln` or `Net3.5\WinAuth-Net3.5.sln` in Visual Studio.
19+
3. Visual Studio > Build > Build Solution.
20+
4. If successful, the executable location should be `bin\Debug\WinAuth.exe` in the solution directory.
21+
22+
## WinAuth.Cli (this fork's maintained target)
23+
24+
Build with Mono's `xbuild`/`msbuild` against the `WinAuth.Cli` project, targeting the same `.sln` structure as above. See the repository's release workflow for the exact CI build steps used to produce the published `winauth-cli-mono.zip` release artifacts.

‎mkdocs-src/index.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# winauth-cli
2+
3+
Cross-platform, GUI-free command-line fork of [WinAuth](https://github.com/winauth/winauth) for running exported authenticator secrets on Linux, macOS, and Windows through Mono — no Windows GUI required.
4+
5+
Supports normal TOTP/HOTP plus Steam Guard's 5-character code format. Entries are stored in a local, optionally password-encrypted XML vault.
6+
7+
## Quickstart
8+
9+
Download the latest release:
10+
11+
<https://github.com/githubhjs/winauth-running-on-all-OS.cli/releases/latest>
12+
13+
```sh
14+
unzip winauth-cli-mono.zip
15+
cd winauth-cli
16+
./winauth-cli import --uri 'otpauth://totp/Example:email?secret=JBSWY3DPEHPK3PXP&issuer=Example'
17+
./winauth-cli add --type steam --name steam --secret JBSWY3DPEHPK3PXP
18+
./winauth-cli code steam
19+
```
20+
21+
See [Installation](installation.md) for Mono setup per platform, and [CLI Usage](usage.md) for the full command reference.
22+
23+
## Why this fork exists
24+
25+
The original WinAuth is a Windows Forms GUI application. This fork extracts the authenticator/TOTP/HOTP/Steam-Guard logic into `WinAuth.Cli`, a Mono-compatible command-line tool, so exported authenticator secrets (e.g. from a `.maFile`, a WinAuth XML export, or any `otpauth://` URI) can be used headlessly on servers, CI, or non-Windows machines — verified working on both an ARM64 Linux workstation and macOS.
26+
27+
The original Windows GUI source is retained in the repository for provenance and compatibility reference, but `WinAuth.Cli` is the maintained target of this fork.

‎mkdocs-src/installation.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Installation
2+
3+
## 1. Get the release
4+
5+
Download `winauth-cli-mono.zip` from the [latest release](https://github.com/githubhjs/winauth-running-on-all-OS.cli/releases/latest) and extract it:
6+
7+
```sh
8+
unzip winauth-cli-mono.zip -d ~/tools/winauth-cli
9+
```
10+
11+
## 2. Install the Mono runtime
12+
13+
**Linux (Ubuntu/Debian):**
14+
```sh
15+
sudo apt-get install -y mono-runtime
16+
```
17+
18+
**macOS (Homebrew):**
19+
```sh
20+
brew install mono
21+
```
22+
23+
**Windows:** the CLI also runs under the standard .NET Framework already present on Windows — Mono is only needed for Linux/macOS.
24+
25+
## 3. Verify
26+
27+
```sh
28+
cd ~/tools/winauth-cli/winauth-cli
29+
./winauth-cli --help
30+
```
31+
32+
Confirmed working on ARM64 Linux (Ubuntu, via `mono-runtime`) and macOS (via Homebrew `mono`).

‎mkdocs-src/usage.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# CLI Usage
2+
3+
```
4+
WinAuth command line authenticator
5+
Usage: winauth-cli [--file PATH] [--password VALUE] COMMAND
6+
```
7+
8+
Global options:
9+
10+
| Option | Description |
11+
|---|---|
12+
| `--file PATH` | Path to the vault XML file (defaults to `~/.config/winauth-cli/winauth.xml`) |
13+
| `--password VALUE` | Vault password, if encrypted. Prefer the `WINAUTH_PASSWORD` environment variable over passing this on the command line — it avoids exposing the password in the process list. |
14+
15+
## Commands
16+
17+
| Command | Description |
18+
|---|---|
19+
| `list` | List all entries in the vault |
20+
| `code NAME\|ID` | Print the current TOTP/HOTP/Steam Guard code for an entry |
21+
| `add --name NAME --secret BASE32 [--type totp\|hotp\|steam] [--issuer TEXT] [--digits N] [--period N] [--counter N] [--algorithm SHA1\|SHA256\|SHA512]` | Add a new entry manually |
22+
| `import --uri otpauth://...` | Import an entry from a standard `otpauth://` URI |
23+
| `show NAME\|ID` | Print an entry's `otpauth://` URI |
24+
| `rename NAME\|ID NEW_NAME` | Rename an entry |
25+
| `remove NAME\|ID` | Remove an entry |
26+
| `sync NAME\|ID COUNTER` | Set an HOTP counter value |
27+
| `export DESTINATION` | Export the vault |
28+
| `passwd --new-password VALUE` | Encrypt, re-key, or decrypt the vault |
29+
30+
## Examples
31+
32+
```sh
33+
# Import from an otpauth:// URI (e.g. from a QR code export)
34+
./winauth-cli import --uri 'otpauth://totp/Example:email?secret=JBSWY3DPEHPK3PXP&issuer=Example'
35+
36+
# Add a Steam Guard entry directly from its Base32 secret
37+
./winauth-cli add --type steam --name steam --secret JBSWY3DPEHPK3PXP
38+
39+
# Get the current code
40+
./winauth-cli code steam
41+
42+
# List everything in the vault
43+
./winauth-cli list
44+
45+
# Encrypt the vault with a password (use WINAUTH_PASSWORD instead of --password where possible)
46+
export WINAUTH_PASSWORD='your-vault-password'
47+
./winauth-cli passwd --new-password "$WINAUTH_PASSWORD"
48+
```
49+
50+
## Vault location
51+
52+
By default, the vault is stored at `~/.config/winauth-cli/winauth.xml`. Keep this file's permissions restrictive (`chmod 600`) since it contains authenticator secrets, whether or not the vault itself is password-encrypted.

‎mkdocs.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
site_name: winauth-cli
2+
site_description: Cross-platform GUI-free WinAuth CLI for Mono on Linux, macOS, and Windows
3+
repo_url: https://github.com/githubhjs/winauth-running-on-all-OS.cli
4+
docs_dir: mkdocs-src
5+
6+
nav:
7+
- Home: index.md
8+
- Installation: installation.md
9+
- CLI Usage: usage.md
10+
- Compiling: compiling.md
11+
12+
theme:
13+
name: readthedocs

0 commit comments

Comments
 (0)