netbox-super-cli 1.6.3__tar.gz → 1.8.0__tar.gz

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.github/workflows/bench.yml

@@ -13,8 +13,8 @@ jobs:
   startup-time:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
       - name: Install
         run: uv sync --all-extras --dev
       - name: Benchmark

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.github/workflows/claude.yml

@@ -41,13 +41,13 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
         with:
           fetch-depth: 1
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@db77d4d3c98f3f6380e7cd45ffba2342a3dbde3c  # v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.github/workflows/docs.yml

@@ -26,9 +26,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
         with:
           enable-cache: true
       - name: Install Python
@@ -36,10 +36,10 @@ jobs:
       - name: Sync deps (runtime + docs)
         run: uv sync --frozen --group docs
       - name: Build site (strict)
-        run: uv run mkdocs build --strict
+        run: uv run zensical build --strict
       - name: Upload Pages artifact
         if: github.ref_type == 'tag'
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
         with:
           path: site
 
@@ -52,4 +52,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346  # v5

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.github/workflows/e2e.yml

@@ -6,6 +6,11 @@ on:
   pull_request:
     paths:
       - 'nsc/http/**'
+      - 'nsc/branching/**'
+      - 'nsc/cli/branch_commands.py'
+      - 'nsc/auth/**'
+      - 'nsc/cli/login_commands.py'
+      - 'nsc/cli/profiles_commands.py'
       - 'nsc/cli/handlers.py'
       - 'nsc/cli/registration.py'
       - 'nsc/cli/writes/**'
@@ -34,8 +39,8 @@ jobs:
     env:
       NETBOX_IMAGE: netboxcommunity/netbox:${{ matrix.netbox-version }}
     steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
       - name: Sync deps
         run: uv sync --frozen
       - name: Start NetBox
@@ -54,3 +59,33 @@ jobs:
       - name: Stop NetBox
         if: always()
         run: docker compose -f tests/e2e/docker-compose.yml down -v
+
+  e2e-branching:
+    name: e2e-branching (v4.7.3 + branching 1.2.2)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      NETBOX_IMAGE: netboxcommunity/netbox:v4.7.3
+      COMPOSE: -f tests/e2e/docker-compose.yml -f tests/e2e/docker-compose.branching.yml
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Build and start NetBox with Branching
+        run: docker compose $COMPOSE up -d --build
+      - name: Wait for NetBox
+        run: tests/e2e/wait_for_netbox.sh
+      - name: Run branching e2e tests
+        env:
+          NSC_E2E: '1'
+          NSC_E2E_BRANCHING: '1'
+          NSC_URL: http://127.0.0.1:8080
+          NSC_TOKEN: '0123456789abcdef0123456789abcdef01234567'
+        run: uv run pytest tests/e2e/test_branching.py -v
+      - name: Dump container logs on failure
+        if: failure()
+        run: docker compose $COMPOSE logs
+      - name: Stop NetBox
+        if: always()
+        run: docker compose $COMPOSE down -v

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.github/workflows/lint.yml

@@ -12,9 +12,9 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
         with:
           enable-cache: true
       - name: Install Python
@@ -31,9 +31,9 @@ jobs:
   docs-reference-fresh:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
         with:
           enable-cache: true
       - name: Install Python
@@ -46,9 +46,9 @@ jobs:
   agents-md-fresh:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
         with:
           enable-cache: true
       - name: Install Python

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.github/workflows/release.yml

@@ -39,7 +39,7 @@ jobs:
     # prerequisites).
     steps:
       - name: Checkout (full history for changelog notes)
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 0
 
@@ -62,7 +62,7 @@ jobs:
           echo "Tag $GITHUB_REF_NAME ($GITHUB_SHA) is on main."
 
       - name: Install uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7.6.0
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
         with:
           enable-cache: true
 
@@ -110,7 +110,7 @@ jobs:
           fi
 
       - name: Publish to PyPI (trusted publishing)
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1
         with:
           # No `password:` — trusted publishing uses the OIDC token bound
           # to id-token: write above. PyPI must have a Trusted Publisher

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.github/workflows/test.yml

@@ -16,9 +16,9 @@ jobs:
       matrix:
         python: ["3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
         with:
           enable-cache: true
       - name: Install Python

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.gitignore

@@ -33,7 +33,7 @@ venv/
 # Local-only design notes (kept out of git history)
 docs/superpowers/
 
-# mkdocs
+# docs build output
 site/
 
 # git worktrees

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/.pre-commit-config.yaml

@@ -27,11 +27,12 @@ repos:
           - click>=8.1
           - typer>=0.12
           - rich>=13.7
-          - httpx>=0.27
+          - httpx2>=2.5
           - "ruamel.yaml>=0.18"
           - structlog>=24.1
           - platformdirs>=4.2
           - textual>=0.50
+          - keyring>=25.0
           - types-PyYAML>=6.0
         args: [--strict]
         files: ^(nsc|scripts)/

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/AGENTS.md

@@ -15,11 +15,12 @@ This is the contributor guide for AI agents (and humans!) modifying this repo. T
 - `nsc/model/` — the normalized command tree (data only, framework-free). The "brain".
 - `nsc/builder/` — converts a parsed schema into a `CommandModel`.
 - `nsc/cli/` — the Typer app; consumes a `CommandModel`.
-- `nsc/http/` — thin httpx wrapper: auth, retries, audit log.
+- `nsc/http/` — thin httpx2 wrapper: auth, retries, audit log.
 - `nsc/output/` — formatters (table/json/jsonl/yaml/csv) + error envelope.
 - `nsc/config/` — config loader + Pydantic models + ruamel.yaml round-trip writer.
 - `nsc/cache/` — disk cache for generated command-models.
 - `nsc/auth/` — login verification helpers (pre-flight probes, token rotate).
+- `nsc/branching/` — NetBox Branching: branch name→schema_id resolution, lifecycle API calls, job polling. Framework-free; `nsc/http` must not import it (the client takes a resolver callable).
 - `nsc/aliases/` — curated alias resolver (`ls`, `get`, `rm`, `search`). Framework-free.
 - `nsc/completion/` — dynamic shell-completion: framework-free providers + cheap on-disk cache probe + Typer `shell_complete` callbacks.
 - `nsc/skill/` — bundle-path helper for the portable `SKILL.md` shipped in the wheel.

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/CHANGELOG.md

@@ -2,6 +2,129 @@
 
 All notable changes to netbox-super-cli are tracked here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) loosely. From v1.0.0 onward, releases follow [Semantic Versioning](https://semver.org/) and the version in `pyproject.toml` matches the git tag. Pre-1.0 milestones (Phase 1-5) were pinned by tag while `pyproject.toml` stayed at `0.0.1`.
 
+## Unreleased
+
+## v1.8.0 — 2026-10-22
+
+Minor release. Adds NetBox Branching support (`--branch`, `NSC_BRANCH`,
+`nsc branch …`), so changes can be staged in a branch, reviewed and merged.
+Also adds OS keyring token storage, lazy TUI pagination with CLI truncation
+notices, and a fix for `nsc login` reporting the wrong user.
+
+### Added
+
+- **NetBox Branching support** ([#166]). Run any command inside a
+  [NetBox Branching](https://netboxlabs.com/docs/extensions/branching/) branch
+  with `--branch NAME`, `NSC_BRANCH`, or a sticky per-profile branch set by
+  `nsc branch use NAME` (`--branch main` forces main). nsc resolves the name
+  to the plugin's `schema_id` and sends `X-NetBox-Branch` on every request.
+  Each command run in a branch prints `⎇ branch: <name>` on stderr, and the
+  TUI header shows it. A missing or non-`ready` branch fails loudly (exit
+  9/12) and never falls back to main. New `nsc branch` group: `list`, `show`,
+  `current`, `create` (waits until ready, `--use`), `use` / `use --main`,
+  `diff`, and `sync` / `merge` / `revert` / `archive` / `delete`. Like every
+  nsc write, these are dry-run unless you pass `--apply`. Conflicts exit 10
+  with `details.conflicts`, and `--acknowledge-conflicts` proceeds anyway.
+  Targets NetBox 4.7 with `netboxlabs-netbox-branching` 1.2.x; a new
+  `e2e-branching` CI job runs it live. See the
+  [branching guide](docs/guides/branching.md).
+- **OS keyring token storage** ([#1]). A new `token: !keyring NAME` config tag
+  resolves the token from the OS keyring (macOS Keychain, Secret Service,
+  Windows Credential Manager) under service `nsc`, username `NAME`.
+  `nsc login --new|--rotate --store keyring [--keyring-name NAME]` verifies the
+  token, writes it to the keyring, and stores only the `!keyring` reference in
+  `~/.nsc/config.yaml`, so the plaintext token never touches disk. Any
+  invocation that builds the dynamic command tree reads the keyring, including
+  bare `nsc` and `nsc --help`; shell completion and the meta commands
+  (`config`, `profiles`, `cache`, `init`, `commands`, `skill`) do not. A missing
+  entry or an unavailable backend yields a `config` error envelope (exit 12),
+  except that `--help` on a static command still prints usage. `nsc login`
+  refuses to overwrite a keyring entry that another profile still references
+  (for example after `nsc profiles rename`) and asks for a distinct
+  `--keyring-name`. `keyring`
+  is a new core dependency, imported lazily so it adds no startup cost. See
+  the new [OS keyring storage guide](docs/guides/keyring.md).
+  `--keyring-name` is stripped of surrounding whitespace, and a blank name is
+  rejected as a usage error before the token prompt.
+
+### Fixed
+
+- **`nsc login` / `nsc profiles add` no longer report a random user** ([#150]).
+  The identity probe used to take the owner of the first row of
+  `/api/users/tokens/`, which for admins is often another user's token. The
+  caller is now identified from the token they presented: v2 (`nbt_…`) tokens
+  are looked up by their non-secret key id; v1 tokens are matched client-side
+  against the retrievable plaintext when NetBox exposes it
+  (`ALLOW_TOKEN_RETRIEVAL`; the plaintext is never sent in a query string), or
+  by every visible token sharing one owner. When the user cannot be determined reliably, nsc prints
+  `authenticated (user unknown)` instead of guessing.
+- **`nsc tui` lists are no longer capped at the first page** ([#151]). The list
+  screen loads 100 rows at a time and fetches the next chunk (following NetBox
+  `next` links) when the cursor reaches the last row or you press <kbd>m</kbd>.
+  The header shows `N of M` (rows loaded vs. the server's `count`). Loading stops
+  at 10,000 rows with a hint to filter instead. A page that fails mid-chunk
+  keeps the rows already received (retry with <kbd>m</kbd>), and a refresh no
+  longer drops selections made beyond the first chunk.
+- **A negative `--limit` is now a usage error** instead of a Python traceback,
+  and `defaults.page_size` must be at least 1.
+- **CLI `list` / `ls` / `search` now report truncation** ([#151]). When the
+  default page size hides records the server still has, a one-line
+  `nsc: showing 50 of 1234 results; pass --all ...` notice is printed on stderr
+  (stdout is unchanged). The default page also no longer fetches one extra page
+  from the server just to discard it.
+- **Pages after the first keep multi-value filters** ([#151]). Following a
+  NetBox `next` link no longer drops repeated query keys, so
+  `--site a --site b --all` returns both sites on every page.
+- **Pagination works when NetBox is served under a sub-path** (`BASE_PATH`,
+  e.g. `https://host/netbox`). The second and later pages no longer 404 from a
+  doubled path prefix.
+
+### Changed
+
+- `NetBoxClient.paginate` now returns a lazy, resumable `Pager`
+  (`nsc/http/pagination.py`) exposing the server `total` and `has_more`, shared
+  by the CLI and the TUI.
+- `nsc login --store` now rejects unknown values. Previously any value other
+  than `env` silently fell back to plaintext, so a typo could write the token
+  to disk. `nsc login --rotate` with no `--store` keeps an existing
+  `!keyring` reference instead of replacing it with plaintext.
+
+[#1]: https://github.com/thomaschristory/netbox-super-cli/issues/1
+[#166]: https://github.com/thomaschristory/netbox-super-cli/issues/166
+[#150]: https://github.com/thomaschristory/netbox-super-cli/issues/150
+[#151]: https://github.com/thomaschristory/netbox-super-cli/issues/151
+
+## v1.7.0 — 2026-09-10
+
+Minor release. Migrates the HTTP stack from `httpx` to Pydantic's maintained
+`httpx2` fork, and keeps `httpx2` off the `nsc --help` cold-start path. No
+user-facing CLI or behavior changes.
+
+### Changed
+
+- **Migrated the HTTP stack from `httpx` to `httpx2`** ([#146]). `httpx2` is
+  Pydantic's stewardship continuation of httpx (same author, API-identical) —
+  httpx itself has seen limited activity, and httpx2 is the reliably-maintained
+  path forward with timely security updates. The dependency floor is now
+  `httpx2>=2.5`; the source layer is a mechanical rename (`import httpx2`,
+  `httpx2.Client`/`httpx2.Response`/…). Test mocking moves from global `respx`
+  to the `pytest-httpx2` plugin's `httpx2_mock` fixture (a `respx.Router`, by
+  respx's own author), which targets httpx2's `httpcore2` transport. No
+  user-facing behavior or CLI surface changes.
+- **httpx2 is now kept off the `nsc --help` / cold-start path** ([#13]). httpx2 is
+  the single heaviest import in the tree (~65ms cold), and nothing on the startup
+  path needs an HTTP client. It was being pulled in eagerly through the
+  runtime → client → retry chain (plus `cache`, `schema`, and `login`
+  command modules). All of these now import httpx2 lazily, at first request. Cold
+  startup drops by roughly httpx2's import cost, bringing the median back under the
+  300ms project target. A new guard test (`test_lazy_httpx2_import.py`) asserts
+  httpx2 never loads on `nsc --help`, and the startup benchmark's threshold is
+  re-baselined to 300ms so an over-threshold skip once again signals a real
+  regression instead of firing on every run.
+
+[#13]: https://github.com/thomaschristory/netbox-super-cli/issues/13
+[#146]: https://github.com/thomaschristory/netbox-super-cli/issues/146
+
 ## v1.6.3 — 2026-07-03
 
 Patch release. Stops an offline instance from rebuilding the command model from

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/CLAUDE.md

@@ -8,11 +8,12 @@ This is the contributor guide for AI agents (and humans!) modifying this repo. T
 - `nsc/model/` — the normalized command tree (data only, framework-free). The "brain".
 - `nsc/builder/` — converts a parsed schema into a `CommandModel`.
 - `nsc/cli/` — the Typer app; consumes a `CommandModel`.
-- `nsc/http/` — thin httpx wrapper: auth, retries, audit log.
+- `nsc/http/` — thin httpx2 wrapper: auth, retries, audit log.
 - `nsc/output/` — formatters (table/json/jsonl/yaml/csv) + error envelope.
 - `nsc/config/` — config loader + Pydantic models + ruamel.yaml round-trip writer.
 - `nsc/cache/` — disk cache for generated command-models.
 - `nsc/auth/` — login verification helpers (pre-flight probes, token rotate).
+- `nsc/branching/` — NetBox Branching: branch name→schema_id resolution, lifecycle API calls, job polling. Framework-free; `nsc/http` must not import it (the client takes a resolver callable).
 - `nsc/aliases/` — curated alias resolver (`ls`, `get`, `rm`, `search`). Framework-free.
 - `nsc/completion/` — dynamic shell-completion: framework-free providers + cheap on-disk cache probe + Typer `shell_complete` callbacks.
 - `nsc/skill/` — bundle-path helper for the portable `SKILL.md` shipped in the wheel.

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: netbox-super-cli
-Version: 1.6.3
+Version: 1.8.0
 Summary: Dynamic NetBox CLI generated from the live OpenAPI schema.
 Project-URL: Homepage, https://github.com/thomaschristory/netbox-super-cli
 Project-URL: Documentation, https://thomaschristory.github.io/netbox-super-cli/
@@ -23,7 +23,8 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: System :: Networking
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1
-Requires-Dist: httpx>=0.27
+Requires-Dist: httpx2>=2.5
+Requires-Dist: keyring>=25.0
 Requires-Dist: platformdirs>=4.2
 Requires-Dist: pydantic>=2.7
 Requires-Dist: rich>=13.7
@@ -64,6 +65,7 @@ One binary, any NetBox version, every plugin endpoint — the schema, not hand-w
 - **Plugins just work.** If your install has plugins, their endpoints appear as commands automatically.
 - **Multi-instance.** Named profiles per NetBox instance, plus env-var overrides.
 - **Safe by default.** POST/PATCH/PUT/DELETE preview as dry-runs unless you pass `--apply`.
+- **NetBox Branching.** Stage changes in a branch (`--branch`, `NSC_BRANCH`, `nsc branch use`), review with `nsc branch diff`, merge with `nsc branch merge --apply`. See [the guide](docs/guides/branching.md).
 - **Agent-friendly.** Deterministic command shape, machine-readable JSON output, stable error envelope with documented exit codes.
 - **Interactive TUI.** `nsc tui` opens a keyboard-driven terminal UI — see below.
 
@@ -208,6 +210,25 @@ The wire body sent to NetBox is **not** redacted — only the audit log. A faile
 
 For a stricter posture, set `audit_redaction: full` in `~/.nsc/config.yaml` (the default is `safe`, the field-level redaction described above). In `full` mode every audit line keeps only `{method, url, status_code, timestamp, profile}` — all request and response bodies are dropped, and the `url` is sanitized (query string and any `user:pass@` credentials stripped).
 
+## NetBox Branching
+
+If your NetBox runs the [Branching plugin](https://netboxlabs.com/docs/extensions/branching/),
+any command can stage its changes in a branch for review:
+
+```sh
+nsc branch create add-london --use            # create, wait until ready, make it sticky
+nsc dcim sites create -f london.yaml --apply  # lands in the branch; stderr shows "⎇ branch: add-london"
+nsc branch diff                               # review the staged changes
+nsc branch merge                              # dry-run, validated server-side
+nsc branch merge --apply                      # merge into main
+nsc branch use --main                         # back to main
+```
+
+`--branch NAME` and `NSC_BRANCH` select a branch for a single command or a
+whole shell, and agents should use these. A merged, missing or not-ready branch
+fails loudly and never falls back to main. See the
+[branching guide](docs/guides/branching.md).
+
 ## Curated aliases
 
 `nsc ls`, `nsc get`, `nsc rm`, and `nsc search` are short verbs over the dynamic

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/README.md

@@ -29,6 +29,7 @@ One binary, any NetBox version, every plugin endpoint — the schema, not hand-w
 - **Plugins just work.** If your install has plugins, their endpoints appear as commands automatically.
 - **Multi-instance.** Named profiles per NetBox instance, plus env-var overrides.
 - **Safe by default.** POST/PATCH/PUT/DELETE preview as dry-runs unless you pass `--apply`.
+- **NetBox Branching.** Stage changes in a branch (`--branch`, `NSC_BRANCH`, `nsc branch use`), review with `nsc branch diff`, merge with `nsc branch merge --apply`. See [the guide](docs/guides/branching.md).
 - **Agent-friendly.** Deterministic command shape, machine-readable JSON output, stable error envelope with documented exit codes.
 - **Interactive TUI.** `nsc tui` opens a keyboard-driven terminal UI — see below.
 
@@ -173,6 +174,25 @@ The wire body sent to NetBox is **not** redacted — only the audit log. A faile
 
 For a stricter posture, set `audit_redaction: full` in `~/.nsc/config.yaml` (the default is `safe`, the field-level redaction described above). In `full` mode every audit line keeps only `{method, url, status_code, timestamp, profile}` — all request and response bodies are dropped, and the `url` is sanitized (query string and any `user:pass@` credentials stripped).
 
+## NetBox Branching
+
+If your NetBox runs the [Branching plugin](https://netboxlabs.com/docs/extensions/branching/),
+any command can stage its changes in a branch for review:
+
+```sh
+nsc branch create add-london --use            # create, wait until ready, make it sticky
+nsc dcim sites create -f london.yaml --apply  # lands in the branch; stderr shows "⎇ branch: add-london"
+nsc branch diff                               # review the staged changes
+nsc branch merge                              # dry-run, validated server-side
+nsc branch merge --apply                      # merge into main
+nsc branch use --main                         # back to main
+```
+
+`--branch NAME` and `NSC_BRANCH` select a branch for a single command or a
+whole shell, and agents should use these. A merged, missing or not-ready branch
+fails loudly and never falls back to main. See the
+[branching guide](docs/guides/branching.md).
+
 ## Curated aliases
 
 `nsc ls`, `nsc get`, `nsc rm`, and `nsc search` are short verbs over the dynamic

netbox_super_cli-1.8.0/SECURITY.md

@@ -0,0 +1,12 @@
+# Security policy
+
+## Supported versions
+
+Only the latest release gets security fixes.
+
+## Reporting a vulnerability
+
+Do not open a public issue. Use the private vulnerability reporting of GitHub:
+[Report a vulnerability](https://github.com/thomaschristory/netbox-super-cli/security/advisories/new)
+(**Security > Report a vulnerability** on the repository). Only the maintainer sees the report.
+The maintainer replies, fixes the problem, and publishes an advisory with the fix.

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/docs/architecture/http-client.md

@@ -1,6 +1,6 @@
 # HTTP client
 
-`nsc/http/` is a thin wrapper around `httpx.Client`.
+`nsc/http/` is a thin wrapper around `httpx2.Client`.
 
 ## What it adds
 
@@ -20,6 +20,15 @@
   `final_attempt`; redaction is applied on every write, so a failed
   retry never unredacts.
 - Pagination helper that follows `next` URLs (used by `--all`).
+- Optional NetBox Branching context. Given a `branch_resolver`, the client
+  resolves the branch lazily on its first request: the resolver's own lookups
+  go out unbranched, and every later request carries
+  `X-NetBox-Branch: <schema_id>`. Resolution is serialized under a lock, so
+  concurrent `--workers` threads wait instead of racing ahead without the
+  header. A failed resolution is stored and raised again on every later call,
+  so once a branch is selected no request can reach main. The resolver
+  itself lives in `nsc/branching/` (`nsc/http` does not import it), and
+  `nsc branch …` commands build a client without one.
 - Audit log appender at `~/.nsc/logs/audit.jsonl` — written for writes
   always, and for any request when `--debug` is set.
 
@@ -27,7 +36,7 @@
 
 Bulk write commands accept `--workers N` (default 1, max 32) to keep up to N
 requests in flight. Concurrency is **thread-based**: a `ThreadPoolExecutor`
-fans the per-record loop out over the single sync `httpx.Client` — there is no
+fans the per-record loop out over the single sync `httpx2.Client` — there is no
 async path. Per-record `--on-error` semantics are preserved regardless of
 worker count. Audit appends are serialized by a module-level lock
 (`_APPEND_LOCK` in `nsc/http/audit.py`) wrapped around the whole
@@ -40,9 +49,9 @@ each record is one well-formed JSON line.
 
 A schema fetch may run before the first command request (only when the
 TTL fast-path misses — see [Caching](caching.md)); it uses its own
-short-lived `httpx.Client` in `nsc/schema/`, not this `NetBoxClient`.
+short-lived `httpx2.Client` in `nsc/schema/`, not this `NetBoxClient`.
 Command requests then go through a single `NetBoxClient` whose
-`httpx.Client` carries the auth header for the life of the process.
+`httpx2.Client` carries the auth header for the life of the process.
 Token rotation via `nsc login --rotate` does NOT invalidate the cached
 model (the schema hash is what keys the cache; the token never affected
 it).
@@ -91,7 +100,7 @@ contract.
 
 ## What it deliberately does not do
 
-- Async — sync only in v1, kept feasible by httpx if a future async path lands.
+- Async — sync only in v1, kept feasible by httpx2 if a future async path lands.
 - Connection pooling across profiles — each profile gets its own `Client`.
 - Caching responses — caching the command-model is enough; caching response
   payloads would surprise users.

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/docs/architecture/overview.md

@@ -1,7 +1,7 @@
 # Architecture overview
 
 `nsc` is layered around a framework-free "brain". The brain — schema parsing
-and the normalized command-model — knows nothing about Typer, Rich, or httpx.
+and the normalized command-model — knows nothing about Typer, Rich, or httpx2.
 The CLI layer consumes the brain; a future TUI could too without changing the
 brain.
 
@@ -11,11 +11,12 @@ nsc/
 ├── model/           # Normalized command-model (data only, framework-free)
 ├── builder/         # Schema → CommandModel
 ├── cli/             # Typer application; walks the model, registers commands
-├── http/            # Thin httpx wrapper: auth, retries, audit
+├── http/            # Thin httpx2 wrapper: auth, retries, audit
 ├── output/          # Formatters (table/json/jsonl/yaml/csv) + error envelope
 ├── config/          # Pydantic config models + ruamel.yaml writer
 ├── cache/           # On-disk cache for generated CommandModels
 ├── auth/            # Login verification helpers (verify probe, token rotate)
+├── branching/       # NetBox Branching: branch lookup, lifecycle calls, job polling
 ├── aliases/         # Curated alias resolver (ls/get/rm/search)
 ├── completion/      # Dynamic shell-completion: providers + cache probe + Typer callbacks
 ├── skill/           # Bundle-path helper for the portable SKILL.md

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/docs/contributing/release-process.md

@@ -11,7 +11,7 @@ on a `chore/release-X.Y.Z` feature branch, gets PR-merged into `main`,
 and only then is `vX.Y.Z` tagged on the resulting merge commit.
 
 The same `v*` tag push also publishes the documentation site.
-`docs.yml` runs build-only (`mkdocs build --strict`) on docs-touching
+`docs.yml` runs build-only (`zensical build --strict`) on docs-touching
 pull requests, but the GitHub Pages **deploy** job only runs on a `v*`
 tag push — the live docs site updates on release, not on merge to
 `main`.

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/docs/getting-started/concepts.md

@@ -70,6 +70,22 @@ nsc dcim devices create --field name=foo --field site=1 --apply
 Add `--explain` to a dry-run to see the schema reasoning ("PATCH because of
 operationId `dcim_devices_partial_update`").
 
+## Branches (NetBox Branching)
+
+If your server runs the NetBox Branching plugin, any command can run inside a
+branch instead of main. Pick one with `--branch NAME`, `NSC_BRANCH=NAME`, or
+make it sticky on the profile with `nsc branch use NAME`. While a branch is
+active, every command prints `⎇ branch: NAME` on stderr. If the branch can't be
+used (merged, missing, not ready), the command fails without sending anything.
+It never quietly falls back to main. See [NetBox Branching](../guides/branching.md).
+
+```sh
+nsc branch create add-london --use
+nsc dcim sites create --field name=London --field slug=london --apply   # staged in the branch
+nsc branch diff
+nsc branch merge --apply
+```
+
 ## Audit log
 
 Every wire request and its response are appended to

{netbox_super_cli-1.6.3 → netbox_super_cli-1.8.0}/docs/getting-started/first-run.md

@@ -54,9 +54,13 @@ nsc login --rotate --profile prod  # rotate the token
 nsc login --fetch-schema           # verify, then fetch & cache the live schema
 ```
 
-`nsc login` probes `GET /api/status/` and `GET /api/users/tokens/?limit=1`
+`nsc login` probes `GET /api/status/` and `GET /api/users/tokens/`
 (both must succeed) and prints `✓ authenticated as <user>, NetBox <version>`
-on success. On failure it emits the standard auth error envelope
+on success. NetBox has no "current user" endpoint, so the user is derived from
+the token you presented; when that can't be done reliably (e.g. a v1 token
+held by an admin who can see other users' tokens) it prints
+`✓ authenticated (user unknown), NetBox <version>` rather than guessing.
+On failure it emits the standard auth error envelope
 (`type: auth`, exit 8).
 
 `--new` requires both `--profile` and `--url`, prompts for the token