Refactor CLI for better DX and Documentation

.github/workflows/dependabot-uv-lock.yml

@@ -1,11 +1,9 @@
 name: "Dependabot: Update uv.lock"
 permissions:
   contents: read
-
 on:
   pull_request_target:
     types: [opened, synchronize]
-
 jobs:
   lock:
     runs-on: ubuntu-latest
@@ -15,21 +13,17 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ github.event.pull_request.head.sha }}
-
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
-
       - name: Update the lockfile
         run: uv lock
-
       - name: Upload uv.lock
         uses: actions/upload-artifact@v4
         with:
           name: uv-lock
           path: uv.lock
-
   commit:
     needs: lock
     runs-on: ubuntu-latest
@@ -42,12 +36,10 @@ jobs:
         with:
           ref: ${{ github.head_ref }}
           token: ${{ secrets.DEPENDABOT_PAT }}
-
       - name: Download uv.lock
         uses: actions/download-artifact@v7
         with:
           name: uv-lock
-
       - name: Commit and push changes
         run: |
           git config --global user.name "github-actions[bot]"

.github/workflows/docs-check.yml

@@ -19,6 +19,8 @@ jobs:
         uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
+      - name: Install pngquant for image optimization
+        run: sudo apt-get update && sudo apt-get install -y pngquant
       - name: Install dependencies
         run: uv sync --all-groups --all-extras --frozen
       - name: Test MkDocs Build (Strict)

.gitignore

@@ -15,6 +15,8 @@ prusa_tokens.json
 .idea/
 .vscode/
 .coverage
+pytest.xml
+pytest-coverage.txt
 .DS_Store
 .pytest_cache/
 .mypy_cache/

.pre-commit-config.yaml

@@ -8,10 +8,13 @@ repos:
           - mdformat-mkdocs[recommended]
           - mdformat-ruff
           - mdformat_frontmatter
+        exclude: ^docs/cli/reference\.md$
   - repo: https://github.com/jackdewinter/pymarkdown
     rev: v0.9.35 # Use the latest version
     hooks:
       - id: pymarkdown
+        name: pymarkdown
+        args: ["-d", "MD041,MD002", "scan"] # Let mdformat handle frontmatter
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:

docs/authentication.md

@@ -0,0 +1,83 @@
+# Authentication
+
+Authentication is a crucial part of interacting with the Prusa Connect API. The
+SDK handles authentication tokens automatically once you've logged in.
+
+## How it Works
+
+The SDK uses the same OAuth 2.0 flow as the official Prusa Connect web interface
+to obtain access and refresh tokens. It uses the PKCE (Proof Key for Code
+Exchange) extension to securely obtain tokens without a client secret (kudos to
+the Prusa Connect team for doing things right and implementing this! :star2:).
+
+1. **Identity Token**: Provides identity information about the user.
+2. **Access Token**: Used to authenticate API requests. Valid for a short period
+   (usually 1 hour).
+3. **Refresh Token**: Used to obtain new access tokens when they expire. Valid
+   for a longer period (usually 30 days).
+
+## Storing Credentials
+
+The SDK stores tokens securely in a user-specific configuration directory using
+`platformdirs`.
+
+- **Linux**: `~/.config/prusa-connect-sdk-client/tokens.json` (or similar)
+- **macOS**:
+  `~/Library/Application Support/prusa-connect-sdk-client/tokens.json`
+- **Windows**: `%APPDATA%\prusa-connect-sdk-client\tokens.json`
+
+The file is JSON-formatted and contains the tokens. It is recommended to
+restrict access to this file.
+
+## Authentication Methods
+
+### 1. CLI Authentication (Recommended)
+
+Run `prusactl auth login` to start an interactive login session. This will
+prompt for your email, password, and 2FA code (if enabled).
+
+### 2. Environment Variables
+
+You can also provide credentials via environment variables, although this is
+generally less secure for long-term use.
+
+- `PRUSA_EMAIL`: Your Prusa Account email.
+- `PRUSA_PASSWORD`: Your Prusa Account password.
+
+Note: Environment variables are used for initial login if provided, but tokens
+are preferred.
+
+### 3. Headless / CI/CD Authentication
+
+For automated environments where interactive login isn't possible, set one of
+the following environment variables. `PrusaConnectClient` detects them
+automatically — no call to `auth login` required.
+
+| Variable            | Value                                            |
+| ------------------- | ------------------------------------------------ |
+| `PRUSA_TOKEN`       | Raw JWT access token string (`ey...`)            |
+| `PRUSA_TOKENS_JSON` | Full token JSON object (access + refresh tokens) |
+
+=== "Raw token"
+
+    ```bash
+    export PRUSA_TOKEN="ey..."
+    ```
+
+=== "Token JSON"
+
+    ```bash
+    export PRUSA_TOKENS_JSON='{"access_token": "ey...", "refresh_token": "ey..."}'
+    ```
+
+!!! tip "Getting the raw token"
+
+    Run `prusactl auth print-access-token` to print the current access token to
+    stdout. This is useful for seeding `PRUSA_TOKEN` in a secrets manager or CI
+    environment variable.
+
+### 4. Programmatic Authentication
+
+You can use `prusa.connect.client.auth.interactive_login` to perform the login
+flow in your own application. See the [SDK Quickstart](sdk/quickstart.md) for an
+example.

docs/cli/quickstart.md

@@ -0,0 +1,135 @@
+# CLI Quickstart
+
+This guide assumes you have already installed `prusactl` using `pipx`. If not,
+please see the [Installation](../installation.md) guide.
+
+## Step 1: Authenticate
+
+Run the following command in your terminal to log in to your Prusa Account. This
+will save a secure token locally to your user configuration directory.
+
+```bash
+prusactl auth login
+```
+
+*Follow the interactive prompts to enter your credentials and 2FA code (if
+required).*
+
+The CLI will display a success message and save your credentials securely.
+
+## Step 2: Verify Authentication
+
+You can check your current authentication status at any time:
+
+```bash
+prusactl auth show
+```
+
+## Step 3: List Your Printers
+
+Now that you are authenticated, list your printers:
+
+```bash
+prusactl printer list
+```
+
+## Step 4: Set a Default Printer
+
+Most commands require a printer UUID. To avoid typing it every time, set a
+default:
+
+```bash
+prusactl printer set-current <uuid>
+```
+
+Once set, commands like `prusactl printer show`, `prusactl stats usage`, and
+others will automatically use this printer.
+
+## Step 5: Monitor Printer Statistics
+
+Track usage over time with the `stats` command group:
+
+```bash
+# Printing time vs idle time for the last 7 days
+prusactl stats usage
+
+# Material consumption
+prusactl stats material --days 30
+
+# Job success/failure breakdown
+prusactl stats jobs
+
+# Planned task schedule (hour-by-hour heatmap)
+prusactl stats planned
+```
+
+All `stats` subcommands accept `--from` and `--to` date flags for custom date
+ranges, and `--days N` as a shorthand for the last N days.
+
+## Step 6: Work with Teams and Cameras
+
+List the teams you belong to and manage cameras:
+
+```bash
+# Teams
+prusactl team list
+prusactl team show          # Show default team details
+
+# Cameras
+prusactl camera list
+prusactl camera snapshot <camera-id> --output snapshot.jpg
+prusactl camera show <camera-id>
+```
+
+## Step 7: Configure Defaults
+
+Set defaults for team and camera to avoid passing IDs repeatedly:
+
+```bash
+prusactl team set-current <team-id>
+prusactl camera set-current <camera-id>
+```
+
+## Step 8: Enable Shell Completion
+
+`prusactl` supports tab completion for all commands and flags. Install it for
+your shell:
+
+```bash
+prusactl --install-completion
+```
+
+Restart your shell (or source your profile) to activate it.
+
+## Step 9: Explore Commands
+
+Use the `--help` flag to discover available commands and flags at any level:
+
+```bash
+prusactl --help
+prusactl printer --help
+prusactl stats --help
+```
+
+## Configuration File
+
+Settings like default printer, team, and camera IDs are stored in a JSON file in
+your platform config directory:
+
+| Platform | Path                                                                 |
+| -------- | -------------------------------------------------------------------- |
+| Linux    | `~/.config/prusa-connect-sdk-client/config.json`                     |
+| macOS    | `~/Library/Application Support/prusa-connect-sdk-client/config.json` |
+| Windows  | `%APPDATA%\prusa-connect-sdk-client\config.json`                     |
+
+You can edit this file directly. Supported keys:
+
+```json
+{
+  "default_printer_id": "your-printer-uuid",
+  "default_team_id": 12345,
+  "default_camera_id": "your-camera-id"
+}
+```
+
+Environment variables (e.g. `DEFAULT_PRINTER_ID`) override file values.

docs/cli_reference.md → docs/cli/reference.md

@@ -1,7 +1,3 @@
----
-comments: false
----
-
 # CLI Reference
 
 ::: cyclopts

docs/examples.md

@@ -2,24 +2,10 @@
 
 ## Headless Authentication (CI/CD)
 
-For environments where interactive login isn't possible (like CI/CD pipelines or
-servers), you can use environment variables.
-
-1. **Option A: Raw Token** Set the `PRUSA_TOKEN` environment variable with your
-   raw JWT access token.
-
-    ```bash
-    export PRUSA_TOKEN="ey..."
-    ```
-
-2. **Option B: Token JSON** Set the `PRUSA_TOKENS_JSON` environment variable
-   with the full JSON object containing access and refresh tokens.
-
-    ```bash
-    export PRUSA_TOKENS_JSON='{"access_token": "...", "refresh_token": "..."}'
-    ```
-
-The `PrusaConnectClient` will automatically detect these variables.
+For environments where interactive login isn't possible, use the `PRUSA_TOKEN`
+or `PRUSA_TOKENS_JSON` environment variables. See
+[Authentication](authentication.md#3-headless-cicd-authentication) for full
+details.
 
 ## Controlling a Printer