netbox-super-cli 1.7.0__tar.gz → 1.8.1__tar.gz

{netbox_super_cli-1.7.0 → netbox_super_cli-1.8.1}/.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.7.0 → netbox_super_cli-1.8.1}/.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.7.0 → netbox_super_cli-1.8.1}/.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
@@ -39,7 +39,7 @@ jobs:
         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.7.0 → netbox_super_cli-1.8.1}/.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.7.0 → netbox_super_cli-1.8.1}/.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.7.0 → netbox_super_cli-1.8.1}/.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.7.0 → netbox_super_cli-1.8.1}/.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.7.0 → netbox_super_cli-1.8.1}/.pre-commit-config.yaml

@@ -32,6 +32,7 @@ repos:
           - 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.7.0 → netbox_super_cli-1.8.1}/AGENTS.md

@@ -20,6 +20,7 @@ This is the contributor guide for AI agents (and humans!) modifying this repo. T
 - `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.7.0 → netbox_super_cli-1.8.1}/CHANGELOG.md

@@ -2,6 +2,115 @@
 
 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.1 — 2026-10-22
+
+Patch release. Fixes two NetBox Branching issues found after v1.8.0.
+
+### Fixed
+
+- **`--branch` after a subcommand no longer switches branches** ([#170]). It is
+  a global option only before the subcommand. After it, `--branch` belongs to
+  that command (for example a plugin's `branch` filter) and is left alone.
+- **Branch failures while loading `--saved` filters honour `-o json`** ([#173]).
+  They now emit the branch error's structured envelope (with its usual exit
+  code) in the requested format instead of falling through to the catch-all
+  table renderer. `nsc --branch X <meta command>` (e.g. `profiles list`) is
+  also recognised as a meta command again instead of bootstrapping the schema.
+
+## 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
+[#170]: https://github.com/thomaschristory/netbox-super-cli/issues/170
+[#173]: https://github.com/thomaschristory/netbox-super-cli/issues/173
+[#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

{netbox_super_cli-1.7.0 → netbox_super_cli-1.8.1}/CLAUDE.md

@@ -13,6 +13,7 @@ This is the contributor guide for AI agents (and humans!) modifying this repo. T
 - `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.7.0 → netbox_super_cli-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: netbox-super-cli
-Version: 1.7.0
+Version: 1.8.1
 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/
@@ -24,6 +24,7 @@ Classifier: Topic :: System :: Networking
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1
 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.7.0 → netbox_super_cli-1.8.1}/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.1/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.7.0 → netbox_super_cli-1.8.1}/docs/architecture/http-client.md

@@ -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.
 

{netbox_super_cli-1.7.0 → netbox_super_cli-1.8.1}/docs/architecture/overview.md

@@ -16,6 +16,7 @@ nsc/
 ├── 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.7.0 → netbox_super_cli-1.8.1}/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.7.0 → netbox_super_cli-1.8.1}/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

netbox_super_cli-1.8.1/docs/guides/branching.md

@@ -0,0 +1,140 @@
+# NetBox Branching
+
+If your NetBox runs the [NetBox Branching plugin](https://netboxlabs.com/docs/extensions/branching/)
+(`netboxlabs-netbox-branching`), `nsc` can make your changes in a **branch**
+instead of on main. You stage writes in the branch, review the diff, and then
+merge them into main. This works the same way for people and for AI agents.
+
+Requires NetBox 4.7 and plugin 1.2.x (tested against NetBox 4.7.3 and plugin 1.2.2).
+
+```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, not main
+nsc branch diff                        # review what the branch changes
+nsc branch merge                       # dry-run: validates the merge server-side
+nsc branch merge --apply               # merge into main
+nsc branch use --main                  # back to main
+```
+
+## Choosing the branch
+
+Every command, including dynamic resource commands, aliases and the TUI, runs
+in the active branch. `nsc` sends the plugin's `X-NetBox-Branch` header with
+the branch's `schema_id`. You refer to a branch by name, or by schema_id if
+you prefer.
+
+The active branch comes from the first of these that is set:
+
+| Source | Example | Lifetime |
+|---|---|---|
+| `--branch NAME` | `nsc --branch add-london ls sites` | one command |
+| `NSC_BRANCH` | `export NSC_BRANCH=add-london` | the shell / CI job |
+| profile `branch:` | written by `nsc branch use NAME` | sticky, until `nsc branch use --main` |
+
+`--branch main` or `NSC_BRANCH=main` forces main for that invocation even when
+the profile has a sticky branch.
+
+`--branch` is a global option and must come **before** the subcommand
+(`nsc --branch X dcim sites list`). After the subcommand, `--branch` belongs to
+that command, for example the Branching plugin's own `changes list` filter, and
+doesn't switch branches.
+
+`nsc branch use` needs a saved profile to store the branch on. With only
+`NSC_URL`/`NSC_TOKEN` set (no profile), use `NSC_BRANCH` or `--branch`.
+
+## Knowing where you are
+
+When a branch is active, every command prints one line to **stderr**:
+
+```
+⎇ branch: add-london
+```
+
+stdout is untouched, so `-o json` output piped elsewhere stays clean. The TUI
+shows the branch in its header in the warning colour. `nsc branch current`
+prints the active branch and where it came from (`flag`, `env` or `profile`),
+or `main`.
+
+Every request made in a branch is recorded in the [audit log](audit-log.md)
+with its `X-Netbox-Branch` header (the branch's schema_id). When a command
+fails while a branch is active, its error envelope names the branch in
+`details.branch`, whatever the failure is.
+
+A branch that is literally named `main` can still be selected by its
+schema_id. `nsc branch use` stores the schema_id for such a branch, because the
+name would read back as "force main".
+
+## When the branch can't be used
+
+If the active branch doesn't exist, or exists but isn't `ready` (it's
+merged, archived, still provisioning, or failed), the command **fails without
+sending anything** and never falls back to main:
+
+| Situation | Error type | Exit |
+|---|---|---|
+| Branching plugin not installed | `config` | 12 |
+| Branch not found | `not_found` | 9 |
+| Branch not `ready` (e.g. merged) | `config` | 12 |
+| Name matches one branch and schema_id of another | `input_error` | 4 |
+
+The message says how to get back to main: `nsc branch use --main`, or
+`--branch main` for a single command. `nsc branch …` commands never run inside
+a branch, so `nsc branch use --main` always works.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `nsc branch list` | All branches; the active one has `active: true`. |
+| `nsc branch show [NAME]` | One branch (default: the active one). |
+| `nsc branch current` | Active branch and its source, or `main`. No network call. |
+| `nsc branch create NAME [--description] [--use] [--no-wait]` | Create the branch and wait until it's `ready`. `--use` then makes it sticky. |
+| `nsc branch use NAME` / `--main` | Set / clear the profile's sticky branch. Checks that the branch is `ready` first. |
+| `nsc branch diff [NAME]` | Staged changes: action, object type, object, changed fields. `-o json` gives the full plugin records. |
+| `nsc branch sync [NAME]` | Pull main's changes into the branch. |
+| `nsc branch merge [NAME]` | Merge the branch into main. |
+| `nsc branch revert [NAME]` | Undo a merged branch on main. |
+| `nsc branch archive [NAME]` | Archive a merged branch (drops its schema). |
+| `nsc branch delete NAME` | Delete a branch. |
+
+### Dry-run by default
+
+Like every other `nsc` write, `sync`, `merge`, `revert`, `archive` and
+`delete` change nothing unless you pass `--apply`:
+
+- `sync`, `merge` and `revert` without `--apply` still run the plugin's job
+  with `commit: false`, so the server checks that the operation would succeed
+  and then rolls it back.
+- `archive` and `delete` without `--apply` only print what they would do.
+
+`sync`, `merge` and `revert` wait for the background job to finish (up to
+`--timeout`, 600 s by default) and print the job's log lines on stderr. Pass
+`--no-wait` to return as soon as the job is queued.
+
+A job that ends in `errored` exits **4** (`validation`), with the job's error
+in `details.job_error`. This happens, for example, when a Change Request
+policy blocks the merge.
+
+### Conflicts
+
+If main and the branch changed the same fields of an object, `sync` and
+`merge` fail with exit **10** (`conflict`), and `details.conflicts` lists each
+object together with its original, branch and main values. After reviewing
+them, re-run with `--acknowledge-conflicts` to proceed; the branch's values
+win.
+
+## For agents
+
+Agents should set `NSC_BRANCH` rather than `nsc branch use`. It works without
+a saved profile, and it doesn't change the user's config:
+
+```sh
+nsc branch create agent-change-123 -o json
+export NSC_BRANCH=agent-change-123
+nsc dcim devices create -f devices.ndjson --apply -o json
+nsc branch diff agent-change-123 -o json   # hand this to a human for review
+```
+
+The commands are the same for people and agents. Whether an agent may run
+`nsc branch merge --apply` is up to the session's own rules; `nsc` doesn't
+enforce it.