@kolatts/pncli 5.3.0 → 6.0.0

package/dist/{config-Y6IE6GY7.js → config-5LC7ZTEP.js}

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  envOverriddenSecretPaths,
   getGlobalConfigPath,
   loadConfig,
   loadJsonFile,
@@ -9,9 +10,10 @@ import {
   setRepoConfigValue,
   writeGlobalConfig,
   writeRepoConfig
-} from "./chunk-QHJ2HM5J.js";
+} from "./chunk-WDWAPTVC.js";
 import "./chunk-HRNOAQDN.js";
 export {
+  envOverriddenSecretPaths,
   getGlobalConfigPath,
   loadConfig,
   loadJsonFile,
@@ -22,4 +24,4 @@ export {
   writeGlobalConfig,
   writeRepoConfig
 };
-//# sourceMappingURL=config-Y6IE6GY7.js.map
+//# sourceMappingURL=config-5LC7ZTEP.js.map

package/dist/{http-V7PZD7LE.js → http-DJSGEGD6.js}

@@ -2,11 +2,11 @@
 import {
   HttpClient,
   createHttpClient
-} from "./chunk-2J2HAFKO.js";
+} from "./chunk-4FR4WGNR.js";
 import "./chunk-BOFSNQQ2.js";
 import "./chunk-HRNOAQDN.js";
 export {
   HttpClient,
   createHttpClient
 };
-//# sourceMappingURL=http-V7PZD7LE.js.map
+//# sourceMappingURL=http-DJSGEGD6.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolatts/pncli",
-  "version": "5.3.0",
+  "version": "6.0.0",
   "description": "The Paperwork Nightmare CLI — structured JSON access to Jira, Bitbucket, GitHub, Confluence, Azure DevOps, SonarQube, Jenkins, and more, built for AI coding agents. Connectivity without MCP.",
   "type": "module",
   "bin": {

package/skills/pncli/SKILL.md

@@ -9,7 +9,7 @@ metadata:
   services: config
 ---
 
-pncli gives AI agents and humans unified CLI access to enterprise tools: Jira, Bitbucket, GitHub, Confluence, SonarQube, SDElements, Azure DevOps, Jenkins, Artifactory, Checkmarx, Contrast Security IAST, Sonatype IQ Server, OpenShift / Kubernetes, Dynatrace, LogScale, Split.IO, Figma, and Alation.
+pncli gives AI agents and humans unified CLI access to enterprise tools: Jira, Bitbucket, GitHub, Confluence, SonarQube, SDElements, Azure DevOps, Jenkins, Artifactory, Checkmarx, Contrast Security IAST, Sonatype IQ Server, OpenShift / Kubernetes, Dynatrace, LogScale, Split.IO, Figma, Alation, and Sauce Labs.
 
 Every service authenticates with a long-lived credential you generate once in that tool's own UI and put in an env var or the config file — for almost all of them a personal access token that goes straight into a header. Alation is the exception: you configure its refresh token, and pncli exchanges it for short-lived API tokens on every run without any interaction. If a tool you need is missing from the table below, it is not out of scope by default — pncli covers enterprise tooling broadly, and the only hard requirement is a credential you can generate once with no browser or interactive step at use time.
 
@@ -74,9 +74,22 @@ network stay direct while SaaS ones route out through the proxy. If a proxy
 variable is set but the proxy cannot be configured, pncli warns on stderr rather
 than silently bypassing it.
 
-TLS verification is **off** by default, because most self-hosted enterprise
-installs sit behind SSL-inspecting proxies that break the certificate chain.
-Set `PNCLI_VERIFY_TLS=1` to turn it back on.
+TLS certificate verification is always **on**, and pncli trusts the OS
+certificate store alongside Node's bundled CAs. If your IT department has
+installed the SSL-inspecting proxy's root certificate on your machine (the usual
+case: it is what makes your browser work), pncli trusts it too, with nothing to
+set. If a certificate still fails, pncli's error says why and how to fix it:
+
+- **Untrusted certificate** — install the proxy's or internal CA's root in the
+  OS store, or point `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` at it. For a
+  self-signed server, export its certificate from the browser and point
+  `NODE_EXTRA_CA_CERTS` at that file.
+- **Hostname mismatch** — use the host name the certificate was issued for in
+  `baseUrl`, usually the fully qualified name rather than a short alias or IP.
+
+Set `NODE_USE_SYSTEM_CA=0` to trust only Node's bundled CAs. (Earlier versions
+disabled verification by default and used `PNCLI_VERIFY_TLS=1` to opt back in;
+that variable is no longer read.)
 
 ## Large text fields (descriptions, acceptance criteria)
 
@@ -106,8 +119,10 @@ Each service has its own file in this skill with the config keys and example val
 | LogScale | `logscale.md` | Log queries, repository listing |
 | Split.IO | `splitio.md` | Feature flag discovery, targeting updates, Change Requests |
 | Figma | `figma.md` | Design files, comments, version history |
+| Sauce Labs | `saucelabs.md` | Test jobs and builds, real-device inventory and availability, device sessions, Sauce Connect tunnels |
 | Alation | `alation.md` | Data catalog metadata (data sources, schemas, tables, columns), search, Document Hubs |
 | Skills Marketplace | `marketplace.md` | Org plugins and shipped AGENTS.md / CLAUDE.md from git marketplaces |
+| Skills guide | `skills-guide.md` | How skills management fits together: sources, agent hosts, scopes, sync, private-repo auth, OS keychain |
 
 ## Installing skills
 
@@ -115,7 +130,7 @@ The skills bundled with pncli install into a repo with `pncli skills install` (d
 
 Installed skills are a copy — after upgrading pncli, re-run `pncli skills install` to refresh them. `skills list` and `skills status` warn when the installed copy came from a different pncli version.
 
-Org-internal plugins come from a git-hosted marketplace: `pncli skills marketplace add <git-clone-url> --all-agents` registers one and installs every plugin into all three agent hosts, and `pncli skills marketplace sync --marketplace all --all-agents` keeps them current. A marketplace can also ship an `instructions/AGENTS.md` and `instructions/CLAUDE.md`; `add` and `sync` merge those into each agent's user-level instructions file (`~/.codex/AGENTS.md`, `~/.copilot/copilot-instructions.md`, `~/.claude/CLAUDE.md`) as a marked block that leaves your own content untouched — `pncli skills marketplace instructions list|install|remove` manages them. `pncli skills status`, `pncli skills locations`, and `pncli doctor` show what is installed and where. The full workflow is in the `marketplace.md` file that ships inside the installed skill, and `pncli skills marketplace --help` summarises it.
+Org-internal plugins come from a git-hosted marketplace: `pncli skills marketplace add <git-clone-url> --all-agents` registers one and installs every plugin into all three agent hosts, and `pncli skills marketplace sync --marketplace all --all-agents` keeps them current. A marketplace can also ship an `instructions/AGENTS.md` and `instructions/CLAUDE.md`; `add` and `sync` merge those into each agent's user-level instructions file (`~/.codex/AGENTS.md`, `~/.copilot/copilot-instructions.md`, `~/.claude/CLAUDE.md`) as a marked block that leaves your own content untouched — `pncli skills marketplace instructions list|install|remove` manages them. `pncli skills status`, `pncli skills locations`, and `pncli doctor` show what is installed and where. The full workflow is in the `marketplace.md` file that ships inside the installed skill, and `pncli skills marketplace --help` summarises it. For the concepts behind all of this — where skills come from, how they stay current, and how private marketplaces authenticate — run `pncli skills guide` (or read `skills-guide.md`).
 
 ## Setup walkthrough
 
@@ -159,10 +174,14 @@ Review results. If any service shows `ok: false`, help troubleshoot the URL or c
 pncli config show
 ```
 
+**Keeping tokens out of plaintext** — `pncli config keychain migrate` moves every secret in `~/.pncli/config.json` into the OS keychain (macOS Keychain, Windows Credential Manager, Secret Service) and leaves `keychain:` references in their place; `--to config` moves them back. `PNCLI_*` environment variables still take precedence.
+
 **Troubleshooting** — when any command fails unexpectedly, run:
 
 ```
 pncli doctor
 ```
 
-It reports config-file health, credential validity per service, and skill install state (including stale skills) in one JSON envelope, with a `problems` array listing suggested fixes. Add `--offline` to skip the network checks.
+It reports config-file health, credential validity per service, keychain references that do not resolve, git authentication for marketplace hosts (GitHub token scope, expiry, and SSO authorization), and skill install state (including stale skills) in one JSON envelope, with a `problems` array listing suggested fixes. Add `--offline` to skip the network checks.
+
+When a clone fails with "repository not found" or an auth error, `pncli git credentials inspect` shows which credential git actually uses for each remote (after `insteadOf` rewriting, or from Git Credential Manager / the `gh` CLI / the OS keychain), and whether it can read the repo; `--scan <dir>` checks every clone under a folder, and `pncli git credentials stored` lists what the credential stores hold. See `github.md`.

package/skills/pncli/ado.md

@@ -51,3 +51,7 @@ pncli ado work schema --example-only > wi.json
 pncli ado work create --type Bug --input-file wi.json
 pncli ado work update --id 123 --input-file wi.json --field Priority=1   # flag wins, and it's reported
 ```
+
+## Skills marketplaces on this host
+
+A skills marketplace repository on this host (see `marketplace.md`) with no `--token` of its own uses `ado.pat` (`PNCLI_ADO_PAT`) for clone and pull, and for `pncli skills git-auth`. The PAT needs the Code (Read) scope.

package/skills/pncli/bitbucket.md

@@ -38,3 +38,7 @@ pncli bitbucket --project MYPROJ create-repo --name my-new-repo
 # With a description and explicit project flag
 pncli bitbucket create-repo --project MYPROJ --name my-new-repo --description "My project"
 ```
+
+## Skills marketplaces on this host
+
+A skills marketplace repository on this host (see `marketplace.md`) with no `--token` of its own uses `bitbucket.pat` (`PNCLI_BITBUCKET_PAT`) for clone and pull, and for `pncli skills git-auth`. Bitbucket Data Center personal access tokens are usually sent with your Bitbucket username: add the marketplace with `--username <you>`, or set it later with `pncli skills marketplace update <name> --username <you>`.

package/skills/pncli/github.md

@@ -65,3 +65,40 @@ pncli github resolve-thread --thread-id PRT_kwDOHfWCIM4APCA
 `list-review-threads` returns the first 100 threads with their resolution status,
 file path/line, and first 10 comments. If a PR has more than 100 threads, a warning
 is written to stderr.
+
+## Which token does a clone use? (`pncli git credentials`)
+
+Classic-PAT setups usually put the token in a gitconfig rewrite such as
+`url."https://<classic-PAT>@github.com/acme/".insteadOf "https://github.com/acme/"`, while Git Credential
+Manager, the `gh` CLI, or the Windows Credential Manager may hold other tokens for the same host. A repo outside
+every mapping silently clones anonymously and fails as "repository not found"; a mapped token may be valid but
+unable to see a particular repo; a stored token may be shadowed by another helper. These commands work on any
+clone, not just skills marketplaces, and never print a token — only its type and a fingerprint (`ghp_…a1b2`):
+
+```
+pncli git credentials inspect                          # every remote of the current clone
+pncli git credentials inspect ~/src/tools --remote upstream
+pncli git credentials inspect https://github.com/acme/tools.git
+pncli git credentials inspect --scan ~/src --problems-only   # clones that are unmapped or lack access
+pncli git credentials mappings                         # every insteadOf rewrite and URL-scoped helper, tokens checked
+pncli git credentials stored                           # what the credential stores hold, and what git actually sends
+pncli git credentials forget --host github.com --username octo   # drop a stale stored credential
+```
+
+- **`inspect`** — per remote: the URL as configured, the URL git uses after `insteadOf` rewriting, the mapping
+  that applied, and where the credential comes from (`insteadOf`, the `url` itself, a `helper`, or `none`). For a
+  helper it names the kind — Git Credential Manager, wincred, osxkeychain, libsecret, store, `gh`, pncli — and
+  GCM's backing store (`wincredman`, `dpapi`, `keychain`, `secretservice`, …). Online it runs an authenticated
+  `git ls-remote`, and for GitHub reports the account, a classic token missing `repo`, SAML SSO authorization,
+  expiry, and whether the token can see **this** repository — each problem with a concrete fix, such as the exact
+  `insteadOf` line to add for an unmapped org.
+- **`stored`** — the Windows Credential Manager's `git:` entries (Git Credential Manager and wincred), the plaintext
+  `~/.git-credentials` file, and the macOS Keychain's git entries (metadata only), plus what git actually sends per
+  host and per stored path. Flags stored tokens that GitHub rejects or that expire soon, several accounts for one
+  host, plaintext storage, and **shadowed** entries — a stored credential git never sends because another helper
+  (typically `gh auth setup-git`) answers first.
+- **`forget`** — `git credential reject` for one host (and optionally account or path), which every helper
+  implements; it reports the fingerprint before and after. A shadowed Windows entry cannot be reached this way —
+  `stored` gives the exact `cmdkey /delete:` command instead.
+
+`--offline` skips every network check.

package/skills/pncli/jira.md

@@ -1,6 +1,6 @@
 # Jira
 
-Enables: `pncli jira get-issue`, `create-issue`, `update-issue`, `search`, `list-boards`, `list-sprints`, `set-sprint`, and more — get, create, and update issues, transitions, comments, attachments, custom fields, and sprints.
+Enables: `pncli jira get-issue`, `create-issue`, `update-issue`, `search`, `list-boards`, `list-sprints`, `set-sprint`, `log-work`, and more — get, create, and update issues, transitions, comments, attachments, custom fields, sprints, and worklogs.
 
 ## Required config
 
@@ -42,6 +42,17 @@ pncli jira set-sprint --key ACME-123 --sprint <sprint-id>
 
 `list-sprints` output includes `startDate`/`endDate`/`state`/`goal` for each sprint.
 
+## Worklogs
+
+```
+pncli jira log-work --key ACME-123 --time-spent "2h 30m" --comment "Investigated the failing build"
+pncli jira log-work --key ACME-123 --time-spent "1d" --started 2024-01-15T09:00:00.000+0000
+```
+
+`--time-spent` uses Jira's own duration format (`1d`, `2h 30m`, `45m`, ...). `--started` takes
+Jira's datetime format (`yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g. `2024-01-15T09:00:00.000+0000`) and
+defaults to now when omitted.
+
 ## Custom fields
 
 Register a custom field once so `--field <Name>=value` and `--input-file` can address it by
@@ -60,6 +71,36 @@ mangle nested double quotes inside a single-quoted argument, which silently stor
 value. `pncli jira fields` prints what's currently registered; `pncli jira fields --discover`
 fetches field metadata straight from the Jira API instead.
 
+Registration is only needed to address a field by **friendly name**, or to get automatic
+value shaping from `type`. Both `--field` and `--fields-file` accept an unregistered raw
+Jira field id or name directly (e.g. `--field fixVersions=@versions.json`,
+`{"fixVersions": [...]}` in a `--fields-file` JSON file) — nothing needs to be pre-registered
+just to use a standard field like `fixVersions` or a custom field you already know the
+`customfield_NNNNN` id for. Registration only fails for a key that still has whitespace in
+it and isn't a registered friendly name — that's almost always a typo.
+
+Some select-type fields (a "Crew" picker, for example) reject the display text you see in
+Jira's UI and only accept the option's numeric key. Run `pncli jira fields --discover
+--project <key>` to see each field's `allowedValues`; if a field's values are `{id, value}`
+pairs rather than plain strings, register it with `"type":"option-id"` and pass the numeric
+`id`, not the display text. **Sprint** is not a custom field at all — don't try to set it
+via `--field` or `--fields-file`; use `pncli jira set-sprint --key <key> --sprint <id>` after
+the issue exists, with the id from `pncli jira list-sprints`.
+
+### PowerShell-safe JSON values
+
+Passing JSON inline in `--field Name={"a":1}` is unreliable in PowerShell — its argument
+parser mangles embedded quotes before pncli ever sees them. Use the `@file` form instead,
+which sidesteps shell quoting entirely:
+
+```powershell
+'{"steps":[{"action":"click"}]}' | Out-File -Encoding utf8 steps.json
+pncli jira create-issue --project ACME --summary "..." --field "Test Steps=@steps.json"
+```
+
+This also applies to `--jql` and any other flag that would otherwise need inline JSON or
+nested quotes on Windows.
+
 ## Large fields via --input-file
 
 `create-issue` and `update-issue` accept `--input-file <path>` (`-` for stdin) instead of, or alongside, individual flags — useful for a long description or many custom fields at once. Run `pncli jira schema` to print the JSON Schema plus a runnable example. Any string value in `fields` may be `@path/to/file` to pull that field's content from a file (e.g. a big HTML description) instead of inlining it. Custom fields resolve by friendly name (if registered — see **Custom fields** above) or by raw id (`customfield_10032`) with no registration required. Individual flags (`--summary`, `--description`, `--field`, ...) override matching keys from the file; overridden keys are printed to stderr and included in the output's `meta.overrides`.
@@ -79,3 +120,6 @@ pncli jira create-issue --input-file issue.json --priority Low   # --priority wi
 - `--assignee` on `create-issue`, `update-issue`, and `assign` takes a **username**, as does
   any `user`-typed custom field passed via `--field`
 - Custom fields discovered with `pncli jira fields --discover`
+- `create-issue` does not check for duplicates before submitting. If a request times out or
+  the response is otherwise ambiguous, run `pncli jira search` for the exact summary before
+  retrying — a timeout does not tell you whether the issue was actually created.

package/skills/pncli/marketplace.md

@@ -27,7 +27,59 @@ pncli skills marketplace add https://bitbucket.imagile.dev/scm/ai/skills.git --n
 
 You can register as many marketplaces as you like — just run `add` again with a different URL. `marketplace setup` is kept as an alias of `add` for backward compatibility.
 
-For a private repo, pass `--token <token>` (a Bitbucket or GitHub access token) — it's stored with that marketplace's entry and injected into the clone/pull URL. For a marketplace hosted on `github.com` (or the host configured as `github.baseUrl`), you can omit `--token` if you already have a working GitHub credential configured (`PNCLI_GITHUB_TOKEN`, `GITHUB_TOKEN`, or `pncli config set github.token`) — `marketplace add` and `marketplace sync` fall back to it automatically. An explicit `--token` on the marketplace always takes priority over that fallback. To rotate a marketplace's own token, re-run `marketplace add <url> --token <new-token>`; a rejected or expired token surfaces as a clear error naming the marketplace rather than raw git output.
+For a private repo, pass `--token <token>` (a Bitbucket or GitHub access token) — it's stored with that marketplace's entry and supplied to git for each clone and pull; it is not left in the clone's `.git/config`. For a marketplace hosted on `github.com` (or the host configured as `github.baseUrl`), you can omit `--token` if you already have a working GitHub credential configured (`PNCLI_GITHUB_TOKEN`, `GITHUB_TOKEN`, or `pncli config set github.token`) — `marketplace add` and `marketplace sync` fall back to it automatically. An explicit `--token` on the marketplace always takes priority over that fallback. To rotate a marketplace's own token, re-run `marketplace add <url> --token <new-token>` (repeat `--keychain` if the old one was stored there, or use `pncli config keychain set marketplaces.<name>.token`); a rejected or expired token surfaces as a clear error naming the marketplace rather than raw git output.
+
+Add `--keychain` to store the token in the OS keychain (macOS Keychain, Windows Credential Manager, Secret Service) instead of plaintext config; the marketplace entry then holds a `keychain:marketplaces.<name>.token` reference.
+
+### Providers: GitHub, Bitbucket, Azure DevOps
+
+A marketplace can live on any HTTPS git host. pncli detects the provider from your configured service hosts and the URL shape (`/_git/` is Azure DevOps, `/scm/` is Bitbucket Data Center), and uses it to pick a fallback token when the marketplace has none of its own:
+
+| Provider | Example clone URL | Fallback token (when no `--token`) |
+|---|---|---|
+| GitHub / GitHub Enterprise | `https://ghe.imagile.dev/ai/skills.git` | `PNCLI_GITHUB_TOKEN` / `GITHUB_TOKEN` / `github.token` (github.com or the host of `github.baseUrl`) |
+| Bitbucket Data Center | `https://bitbucket.imagile.dev/scm/ai/skills.git` | `PNCLI_BITBUCKET_PAT` / `bitbucket.pat` (the host of `bitbucket.baseUrl`) |
+| Azure DevOps Server | `https://ado.imagile.dev/DefaultCollection/Platform/_git/skills` | `PNCLI_ADO_PAT` / `SYSTEM_ACCESSTOKEN` / `ado.pat` (the host of `ado.baseUrl`) |
+| anything else | `https://git.imagile.dev/ai/skills.git` | none; pass `--token` |
+
+Each marketplace keeps its own `--token`, so marketplaces on the same host (or on different providers) can use different secrets. Pass `--provider github|bitbucket|ado|git` if detection guesses wrong.
+
+The token is sent with a username: `x-access-token` on github.com, `x-token-auth` everywhere else (unchanged from earlier versions; Azure DevOps accepts any username with a PAT). **Bitbucket Data Center personal access tokens are usually sent with your Bitbucket username** — set it per marketplace:
+
+```
+pncli skills marketplace add https://bitbucket.imagile.dev/scm/ai/skills.git --token <token> --username jdoe --all-agents
+pncli skills marketplace update internal-ai --username jdoe          # for one you already added
+```
+
+### Rotate a token or change credentials (`update`)
+
+```
+pncli skills marketplace update internal-ai --token <new-token> [--keychain]
+pncli skills marketplace update internal-ai --username jdoe
+pncli skills marketplace update internal-ai --clear-token            # use the provider fallback instead
+pncli skills marketplace update internal-ai --provider bitbucket
+```
+
+`update` changes the stored entry only — no re-clone, no reinstall. A keychain entry the marketplace no longer points at is deleted.
+
+### Let git itself authenticate (`git-auth`)
+
+pncli's own clone and pull are covered above, but an agent host that clones a marketplace itself (e.g. Claude Code's `/plugin marketplace add`) runs plain `git`, which has no credential for it. Give it one:
+
+```
+pncli skills git-auth enable                                   # every marketplace that has a credential
+pncli skills git-auth enable --marketplace internal-ai --mode keychain
+pncli skills git-auth status                                   # per marketplace: mode, username, token source, match
+pncli skills git-auth disable [--marketplace internal-ai] [--forget-keychain]
+```
+
+- Entries are **scoped to each marketplace's repository URL** (with and without `.git`), for example `credential.https://bitbucket.imagile.dev/scm/ai/skills.git.helper`. git consults them only for that repository, so every other repo on the same host keeps using your own login, untouched.
+- `--mode helper` (default) writes an empty reset entry, `!pncli skills git-credential --marketplace '<name>'`, then whatever helpers git used for that repo before (the host's `gh auth setup-git` entry, Git Credential Manager, osxkeychain). pncli answers with that marketplace's own credential — the same username and token its clone and pull use — resolved from env → config → keychain, so nothing is copied into gitconfig and rotation needs no re-run. If pncli cannot answer, git falls through to your helpers as before.
+- `--mode keychain` stores the credential in git's own credential store via `git credential approve`, keyed to the repository (a repo-scoped `useHttpPath`). It works where pncli is not on git's `PATH`, but must be re-run after rotating the token; `pncli doctor` detects the stale copy.
+- `--host <host>` writes a whole-host entry instead, answered with the provider token pncli has for that host. Use it deliberately: it puts that token in front of every repo on the host.
+- `disable` restores exactly what `enable` replaced; pncli records it under `gitAuth.scopes` in its global config. `enable` also rewrites any clone whose `origin` still carries an embedded token.
+
+`pncli doctor` reports a `gitAuth` entry per marketplace: provider, mode, username, token source, whether git's credential matches pncli's, and clones with embedded tokens. Online, it runs an authenticated `git ls-remote` with exactly that username and token — which catches a wrong Bitbucket username as reliably as an expired token — and, for GitHub, reports the token kind (classic `ghp_` vs fine-grained), a missing `repo` scope, SSO authorization, and expiry within 14 days.
 
 If you upgrade pncli from a version that only supported a single marketplace, your existing config is migrated to the multi-marketplace format automatically the first time you run any `marketplace` command — no manual steps required.
 

package/skills/pncli/saucelabs.md

@@ -0,0 +1,175 @@
+# Sauce Labs
+
+pncli calls the Sauce Labs REST API directly with your username and access key; no `saucectl`, Sauce Connect, or other CLI is required.
+
+## Configuration
+
+| Key | Environment variable | CI fallback | Purpose |
+|---|---|---|---|
+| `saucelabs.baseUrl` | `PNCLI_SAUCELABS_BASE_URL` | — | API endpoint for your data center (see below) |
+| `saucelabs.username` | `PNCLI_SAUCELABS_USERNAME` | `SAUCE_USERNAME` | Your Sauce Labs username |
+| `saucelabs.accessKey` | `PNCLI_SAUCELABS_ACCESS_KEY` | `SAUCE_ACCESS_KEY` | Your access key |
+
+Find both the username and the access key in Sauce Labs under **Account → User Settings**. The access key is long-lived; pncli sends it with the username as HTTP Basic auth.
+
+`baseUrl` depends on the data center your account lives in:
+
+| Data center | `baseUrl` |
+|---|---|
+| US West | `https://api.us-west-1.saucelabs.com` |
+| US East | `https://api.us-east-4.saucelabs.com` (real devices only — no virtual-device jobs) |
+| EU Central | `https://api.eu-central-1.saucelabs.com` |
+
+```bash
+pncli config set saucelabs.baseUrl https://api.us-west-1.saucelabs.com
+pncli config set saucelabs.username <your-username>
+pncli config set saucelabs.accessKey <your-access-key>
+pncli config test
+```
+
+Or with environment variables:
+
+```bash
+export PNCLI_SAUCELABS_BASE_URL=https://api.us-west-1.saucelabs.com
+export PNCLI_SAUCELABS_USERNAME=<your-username>
+export PNCLI_SAUCELABS_ACCESS_KEY=<your-access-key>
+```
+
+**CI:** `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` are the names `saucectl`, Sauce Connect, and Sauce's CI integrations already use, so a pipeline that sets them needs only `PNCLI_SAUCELABS_BASE_URL`. Precedence for the username and access key is `PNCLI_SAUCELABS_*` → `SAUCE_*` → `.pncli.json` / `~/.pncli/config.json`.
+
+## Commands
+
+### Account and platform
+
+```bash
+pncli saucelabs status                       # Is Sauce Labs operational? Current wait time
+pncli saucelabs concurrency                  # Allowed vs. in-use VMs and real devices (also verifies credentials)
+pncli saucelabs platforms --api appium       # Supported platforms: all | appium | webdriver
+pncli saucelabs appium-versions              # Appium versions for real-device sessions, with EOL dates
+pncli saucelabs users --phrase jane          # Look up users in your organization
+pncli saucelabs team list
+pncli saucelabs team get <team-id>
+pncli saucelabs team members <team-id>
+```
+
+### Jobs (virtual devices and desktop browsers)
+
+```bash
+pncli saucelabs job list --limit 20 --from 2026-09-01T00:00:00Z
+pncli saucelabs job get <job-id>                  # Status, platform, timings, log and video URLs
+pncli saucelabs job assets <job-id>               # Asset file names (logs, video, screenshots)
+pncli saucelabs job update <job-id> --passed --build release-42 --tags smoke,email
+pncli saucelabs job update <job-id> --public team # public | public restricted | share | team | private
+pncli saucelabs job stop <job-id>
+pncli saucelabs job delete <job-id>
+```
+
+`--from` / `--to` accept Unix seconds or an ISO 8601 date. `--tags` replaces the job's existing tags.
+
+### Real-device jobs
+
+```bash
+pncli saucelabs rdc-job list --limit 20
+pncli saucelabs rdc-job list --live               # Manual (live) tests only
+pncli saucelabs rdc-job get <job-id>              # Device, result, timings, device/network/crash log URLs
+pncli saucelabs rdc-job update <job-id> --failed --name "Gmail rendering"
+pncli saucelabs rdc-job stop <job-id>
+pncli saucelabs rdc-job delete <job-id>
+```
+
+### Builds
+
+`--source` is `vdc` (virtual devices, the default) or `rdc` (real devices).
+
+```bash
+pncli saucelabs build list --source rdc --status failed,error --limit 10
+pncli saucelabs build get <build-id> --source rdc
+pncli saucelabs build jobs <build-id> --failed    # also --errored --passed --running --queued --completed --finished --faulty
+pncli saucelabs build for-job <job-id>            # Which build a job belongs to
+```
+
+### Real devices
+
+```bash
+pncli saucelabs device list --os android --type phone
+pncli saucelabs device list --name "iPhone 1[56].*" --os-version 17
+pncli saucelabs device get iPhone_15_real          # Full hardware and OS descriptor
+pncli saucelabs device status --state available    # Which devices are free right now
+pncli saucelabs device status --private-only
+```
+
+`--name` and `--os-version` are regular expressions on the Sauce side.
+
+### Device sessions (Real Device Access API)
+
+A session reserves a real device and lets you drive it through the API. Close it when you are done — an open session holds a device and counts against your concurrency.
+
+```bash
+# Reserve a device; --wait polls until it is ACTIVE (default timeout 300s)
+pncli saucelabs session create --device-name "Samsung Galaxy S2[34].*" --os android --wait
+pncli saucelabs session create --os ios --duration PT30M --tunnel-name <tunnel-name> --wait
+
+pncli saucelabs session list --state active
+pncli saucelabs session get <session-id>           # State, expiry, Appium URL, live-view link
+
+# Drive the device
+pncli saucelabs session open-url <session-id> https://preview.imagile.dev/welcome-email
+pncli saucelabs session shell <session-id> "getprop ro.build.version.release"   # Android only
+pncli saucelabs session install-app <session-id> storage:filename=app.apk --launch
+pncli saucelabs session installations <session-id>
+pncli saucelabs session launch-app <session-id> --package-name com.google.android.gm
+pncli saucelabs session launch-app <session-id> --bundle-id com.apple.mobilesafari
+pncli saucelabs session uninstall-app <session-id> --package-name <package>
+pncli saucelabs session settings <session-id> --orientation landscape --locale de_DE
+
+# Record a test (a job) inside the session
+pncli saucelabs session start-test <session-id> --name "Welcome email" --build release-42 --video --device-logs
+pncli saucelabs session end-test <session-id> --passed
+pncli saucelabs session tests <session-id>
+
+# Network throttling
+pncli saucelabs session network-profiles <session-id>
+pncli saucelabs session network <session-id> --profile 4G-fast
+pncli saucelabs session network <session-id> --download 1500 --upload 750 --latency 300 --loss 1
+pncli saucelabs session network <session-id> --reset
+
+# Appium
+pncli saucelabs session appium <session-id>
+pncli saucelabs session appium <session-id> --start --appium-version <version>
+
+# Release the device
+pncli saucelabs session delete <session-id>
+```
+
+Limits Sauce Labs enforces, not pncli:
+
+- Sessions default to 6 hours. Public devices cap at 1 hour, private devices at 24 hours; longer `--duration` values are capped rather than rejected.
+- `session shell` works on Android only, and public devices accept only an allowlisted set of commands.
+- `session settings --locale` and `--animations` are Android only; `--orientation` works on both.
+- A `409` on `session create` means your concurrency limit is reached — check `pncli saucelabs concurrency`.
+
+### Sauce Connect tunnels
+
+```bash
+pncli saucelabs tunnel list                        # Full details for your tunnels
+pncli saucelabs tunnel list --all                  # Include tunnels shared with you
+pncli saucelabs tunnel get <tunnel-id>
+pncli saucelabs tunnel jobs <tunnel-id>            # Jobs currently running through it
+pncli saucelabs tunnel stop <tunnel-id>
+```
+
+### App storage
+
+```bash
+pncli saucelabs storage files --kind android --query gmail
+pncli saucelabs storage groups --kind ios
+```
+
+## Not supported
+
+pncli returns JSON from API calls; it does not handle binary content or visual comparison.
+
+- Downloading job assets (videos, logs, screenshots), device screenshots, and pulling or pushing files on a device. `job assets` and the `*_url` fields on jobs give you the links.
+- Uploading apps to app storage.
+- Judging how something renders. To check an email on real devices, reserve a session, `open-url` the email's web view or `launch-app` the mail client, record it with `start-test --video --screenshots`, and review the recording through the job's `video_url` or the session's `liveViewUrl`.
+- Starting a Sauce Connect tunnel. Run Sauce Connect itself, then reference the tunnel with `--tunnel-name`.