nexla-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/.github/workflows/publish-pypi.yml

@@ -20,10 +20,13 @@ jobs:
       - run: python -m build
 
       # Preferred: PyPI Trusted Publishing. Requires a one-time setup on
-      # pypi.org (project nexla-cli -> Settings -> Publishing -> add this
-      # repo + workflow filename + "pypi" environment as a trusted
-      # publisher) -- see README.md's "Publishing to PyPI" section. No
-      # secret/token needed here.
+      # pypi.org, done by the repo owner (not automatable from a workflow
+      # run): project "nexla-cli" -> Settings -> Publishing -> add a
+      # trusted publisher with Owner = this repo's GitHub org/user, repo =
+      # this repo's name, workflow filename = "publish-pypi.yml",
+      # environment name = "pypi" (matches the `environment:` key above).
+      # No secret/token needed once that's configured -- id-token: write
+      # plus the matching environment satisfy PyPI's OIDC handshake.
       - uses: pypa/gh-action-pypi-publish@release/v1
 
       # Optional fallback if Trusted Publishing isn't set up yet: uncomment

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/.github/workflows/release-binaries.yml

@@ -23,9 +23,25 @@ jobs:
         with:
           python-version: "3.12"
       - run: pip install . pyinstaller
-      - run: >
-          pyinstaller --onefile --name ${{ matrix.asset }}
-          scripts/pyinstaller_entry.py
+      - name: Build (bundling SKILL.md/AGENTS.md so `nexla skill install` works from the binary too)
+        shell: python
+        run: |
+          import os
+          import PyInstaller.__main__
+
+          def add_data(src: str) -> str:
+              # PyInstaller's --add-data separator is OS-specific (":" on
+              # posix, ";" on Windows) -- os.pathsep gets this right without
+              # needing per-OS shell branches in this matrix job.
+              return f"src/nexla_cli/{src}{os.pathsep}nexla_cli"
+
+          PyInstaller.__main__.run([
+              "--onefile",
+              "--name", "${{ matrix.asset }}",
+              "--add-data", add_data("SKILL.md"),
+              "--add-data", add_data("AGENTS.md"),
+              "scripts/pyinstaller_entry.py",
+          ])
       - uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.asset }}
@@ -34,6 +50,8 @@ jobs:
   release:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: actions/download-artifact@v4
         with:

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexla-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: Command-line client for the Nexla agent API.
 Project-URL: Homepage, https://github.com/abhishekkumar705/nexla-agent-cli
 Project-URL: Repository, https://github.com/abhishekkumar705/nexla-agent-cli
@@ -52,10 +52,8 @@ npm install -g nexla-cli
 npx nexla-cli sources list
 ```
 
-This installs a prebuilt native binary (published to GitHub Releases by
-`.github/workflows/release-binaries.yml`) behind a thin `npm/` wrapper — no
-Python interpreter needed on the target machine. See `npm/README.md` for how
-releases are cut.
+This installs a prebuilt native binary behind a thin `npm/` wrapper — no
+Python interpreter needed on the target machine.
 
 ### From PyPI
 
@@ -66,30 +64,6 @@ uvx nexla-cli sources list
 pipx install nexla-cli
 ```
 
-Published by `.github/workflows/publish-pypi.yml` — see "Publishing to
-PyPI" below.
-
-## Publishing to PyPI
-
-Tagging a release (`git tag vX.Y.Z && git push --tags` — same tag used to
-trigger `.github/workflows/release-binaries.yml`, see `npm/README.md` for
-the full release checklist) also triggers `publish-pypi.yml`, which builds
-the sdist+wheel and publishes them to PyPI using
-[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) —
-no long-lived API token stored in this repo.
-
-One-time setup required on pypi.org before the first release (repo owner
-only, not automatable from here):
-
-1. Create the `nexla-cli` project on PyPI (or reserve the name).
-2. Project → Settings → Publishing → add a trusted publisher:
-   - Owner: `abhishekkumar705`, repo: `nexla-agent-cli`
-   - Workflow filename: `publish-pypi.yml`
-   - Environment name: `pypi`
-3. Nothing else to configure — no secrets to add. The workflow's
-   `id-token: write` permission plus the `pypi` GitHub Environment satisfy
-   PyPI's OIDC handshake automatically.
-
 ## Quick start
 
 ```bash
@@ -108,21 +82,15 @@ above); alternatively, set the following environment variables directly:
 
 The package ships a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills) (`AGENTS.md` + `SKILL.md`, installed alongside the `nexla_cli` package) encoding invariants an agent can't infer from `--help` alone — output modes, `--dry-run`, `--json`/`--params` precedence, exit codes, and treating API responses as untrusted data.
 
-Claude Code only discovers skills placed at `~/.claude/skills/<name>/SKILL.md` (global) or `.claude/skills/<name>/SKILL.md` (project-local) — a file merely present inside an installed pip package isn't picked up automatically. Symlink it in once, after installing the CLI. `pipx`/`uv tool install` both use an isolated venv, so a plain system `python3 -c "import nexla_cli"` won't find it — locate it inside that isolated venv instead:
+Claude Code only discovers skills placed at `~/.claude/skills/<name>/SKILL.md` (global) or `.claude/skills/<name>/SKILL.md` (project-local) — a file merely present inside an installed package isn't picked up automatically. Install it once, after installing the CLI (works the same way regardless of whether you installed via `uv tool`, `pipx`, `pip`, or the npm-wrapped binary):
 
 ```bash
-mkdir -p ~/.claude/skills/nexla-cli
-
-# if installed with `uv tool install`:
-ln -sf "$(uv tool dir)/nexla-cli/lib/python3."*"/site-packages/nexla_cli/SKILL.md" \
-  ~/.claude/skills/nexla-cli/SKILL.md
-
-# if installed with `pipx install`:
-ln -sf "$HOME/.local/pipx/venvs/nexla-cli/lib/python3."*"/site-packages/nexla_cli/SKILL.md" \
-  ~/.claude/skills/nexla-cli/SKILL.md
+nexla skill install
+# or, for a project-local install instead of the global default:
+nexla skill install --target .claude/skills/nexla-cli
 ```
 
-A symlink (not a copy) means `nexla-cli` upgrades automatically pick up any future skill content updates. Restart Claude Code (or start a new session) after installing for it to be picked up.
+Re-run this after upgrading `nexla-cli` to pick up any skill content changes. Restart Claude Code (or start a new session) afterward for it to be picked up.
 
 ## Global flags
 
@@ -175,6 +143,7 @@ nexla <resource> --help
 | `toolsets` | `list`, `get`, `create`, `update`, `delete`, `add-nexsets` |
 | `tools` | `list`, `get`, `set-runtime-config`, `clear-runtime-config`, `delete` |
 | `mcp-servers` | `list`, `attach`, `sync`, `detach` (nested under a toolset) |
+| `triage` | `errors`, `status`, `run`, `metrics`, `resource-status`, `org-metrics`, `user-metrics`, `notifications`, `search`, `logs`, `quarantine` — flow/log triage via the Nexla monitoring MCP server, not the main API |
 | `context` | `get` |
 | `orgs` | `list`, `get` |
 | `code-containers` | `list` |
@@ -194,3 +163,7 @@ nexla <resource> --help
 | 4 | 401/403 from the API |
 | 5 | 404 |
 | 6 | 5xx from the API |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/README.md

@@ -23,10 +23,8 @@ npm install -g nexla-cli
 npx nexla-cli sources list
 ```
 
-This installs a prebuilt native binary (published to GitHub Releases by
-`.github/workflows/release-binaries.yml`) behind a thin `npm/` wrapper — no
-Python interpreter needed on the target machine. See `npm/README.md` for how
-releases are cut.
+This installs a prebuilt native binary behind a thin `npm/` wrapper — no
+Python interpreter needed on the target machine.
 
 ### From PyPI
 
@@ -37,30 +35,6 @@ uvx nexla-cli sources list
 pipx install nexla-cli
 ```
 
-Published by `.github/workflows/publish-pypi.yml` — see "Publishing to
-PyPI" below.
-
-## Publishing to PyPI
-
-Tagging a release (`git tag vX.Y.Z && git push --tags` — same tag used to
-trigger `.github/workflows/release-binaries.yml`, see `npm/README.md` for
-the full release checklist) also triggers `publish-pypi.yml`, which builds
-the sdist+wheel and publishes them to PyPI using
-[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) —
-no long-lived API token stored in this repo.
-
-One-time setup required on pypi.org before the first release (repo owner
-only, not automatable from here):
-
-1. Create the `nexla-cli` project on PyPI (or reserve the name).
-2. Project → Settings → Publishing → add a trusted publisher:
-   - Owner: `abhishekkumar705`, repo: `nexla-agent-cli`
-   - Workflow filename: `publish-pypi.yml`
-   - Environment name: `pypi`
-3. Nothing else to configure — no secrets to add. The workflow's
-   `id-token: write` permission plus the `pypi` GitHub Environment satisfy
-   PyPI's OIDC handshake automatically.
-
 ## Quick start
 
 ```bash
@@ -79,21 +53,15 @@ above); alternatively, set the following environment variables directly:
 
 The package ships a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills) (`AGENTS.md` + `SKILL.md`, installed alongside the `nexla_cli` package) encoding invariants an agent can't infer from `--help` alone — output modes, `--dry-run`, `--json`/`--params` precedence, exit codes, and treating API responses as untrusted data.
 
-Claude Code only discovers skills placed at `~/.claude/skills/<name>/SKILL.md` (global) or `.claude/skills/<name>/SKILL.md` (project-local) — a file merely present inside an installed pip package isn't picked up automatically. Symlink it in once, after installing the CLI. `pipx`/`uv tool install` both use an isolated venv, so a plain system `python3 -c "import nexla_cli"` won't find it — locate it inside that isolated venv instead:
+Claude Code only discovers skills placed at `~/.claude/skills/<name>/SKILL.md` (global) or `.claude/skills/<name>/SKILL.md` (project-local) — a file merely present inside an installed package isn't picked up automatically. Install it once, after installing the CLI (works the same way regardless of whether you installed via `uv tool`, `pipx`, `pip`, or the npm-wrapped binary):
 
 ```bash
-mkdir -p ~/.claude/skills/nexla-cli
-
-# if installed with `uv tool install`:
-ln -sf "$(uv tool dir)/nexla-cli/lib/python3."*"/site-packages/nexla_cli/SKILL.md" \
-  ~/.claude/skills/nexla-cli/SKILL.md
-
-# if installed with `pipx install`:
-ln -sf "$HOME/.local/pipx/venvs/nexla-cli/lib/python3."*"/site-packages/nexla_cli/SKILL.md" \
-  ~/.claude/skills/nexla-cli/SKILL.md
+nexla skill install
+# or, for a project-local install instead of the global default:
+nexla skill install --target .claude/skills/nexla-cli
 ```
 
-A symlink (not a copy) means `nexla-cli` upgrades automatically pick up any future skill content updates. Restart Claude Code (or start a new session) after installing for it to be picked up.
+Re-run this after upgrading `nexla-cli` to pick up any skill content changes. Restart Claude Code (or start a new session) afterward for it to be picked up.
 
 ## Global flags
 
@@ -146,6 +114,7 @@ nexla <resource> --help
 | `toolsets` | `list`, `get`, `create`, `update`, `delete`, `add-nexsets` |
 | `tools` | `list`, `get`, `set-runtime-config`, `clear-runtime-config`, `delete` |
 | `mcp-servers` | `list`, `attach`, `sync`, `detach` (nested under a toolset) |
+| `triage` | `errors`, `status`, `run`, `metrics`, `resource-status`, `org-metrics`, `user-metrics`, `notifications`, `search`, `logs`, `quarantine` — flow/log triage via the Nexla monitoring MCP server, not the main API |
 | `context` | `get` |
 | `orgs` | `list`, `get` |
 | `code-containers` | `list` |
@@ -165,3 +134,7 @@ nexla <resource> --help
 | 4 | 401/403 from the API |
 | 5 | 404 |
 | 6 | 5xx from the API |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nexla_cli-0.2.1/RELEASING.md

@@ -0,0 +1,43 @@
+# Releasing
+
+This repo ships to three places from one tag push: GitHub Releases (binaries),
+PyPI (sdist/wheel), and npm (wrapper around the binaries). Maintainer-only —
+none of this belongs in `README.md`/`npm/README.md`, since both render on
+public package pages (PyPI's long description and the npm package page).
+
+## Cutting a release
+
+1. Bump the version in both `pyproject.toml` and `npm/package.json` — they
+   must match, since `npm/scripts/install.js` derives the GitHub release tag
+   it downloads from `npm/package.json`'s version.
+2. `git tag vX.Y.Z && git push --tags`. This triggers two workflows:
+   - `.github/workflows/release-binaries.yml` — builds binaries for macOS
+     (arm64), Linux (x64), and Windows (x64) via PyInstaller and attaches
+     them to a new GitHub Release.
+   - `.github/workflows/publish-pypi.yml` — builds the sdist+wheel and
+     publishes to PyPI via Trusted Publishing (OIDC).
+3. Once the GitHub Release assets are up, publish the npm wrapper (not yet
+   automated):
+   ```bash
+   cd npm && npm publish
+   ```
+
+## One-time PyPI Trusted Publishing setup (repo owner only)
+
+Required once before the first PyPI release; see
+`.github/workflows/publish-pypi.yml`'s own comments for the exact steps
+(project name, trusted-publisher owner/repo/workflow filename/environment) —
+kept there since it lives right next to the `id-token: write` permission it
+configures.
+
+## Binary release matrix
+
+Supported platforms: `darwin-arm64`, `linux-x64`, `win32-x64` — see
+`npm/scripts/install.js`'s `ASSETS` map. To support another platform, add an
+entry there and a matching matrix row in `release-binaries.yml`.
+
+Intel Mac (`macos-13`) was dropped from the matrix: GitHub's Intel-macOS
+runner capacity is shrinking as it's phased out, and that job was sitting
+queued 15+ minutes with zero progress while the other three platforms
+finished in under 90s each. Re-add a `macos-13` row + a `darwin-x64` entry
+in `ASSETS` if Intel Mac support is actually needed again.

nexla_cli-0.2.1/npm/README.md

@@ -0,0 +1,8 @@
+# nexla-cli (npm wrapper)
+
+Thin npm package that installs the prebuilt `nexla` binary — no Python
+required. `postinstall` (`scripts/install.js`) downloads the binary matching
+the current OS/arch from the GitHub release tagged `v<package version>`;
+`bin/nexla.js` execs it and forwards argv/stdio/exit code.
+
+Supported platforms: `darwin-arm64`, `linux-x64`, `win32-x64`.

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/npm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexla-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Command-line client for the Nexla agent API (native binary, no Python required)",
   "bin": {
     "nexla": "bin/nexla.js"

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nexla-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "Command-line client for the Nexla agent API."
 readme = "README.md"
 # Same MIT license already declared for this codebase in npm/package.json.

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/src/nexla_cli/AGENTS.md

@@ -50,6 +50,16 @@ response does not guarantee the resource is fully live yet. Poll
 for sources, `source_nexset_id` once schema inference has run) rather than
 assuming the `create` response reflects final state.
 
+`sources get`/`nexsets get`/`sinks get` all take `--wait-until` to do this
+polling for you instead of hand-writing a `for i in ...; sleep N; done`
+shell loop — `--wait-until <field>` blocks until that dotted field is
+truthy (e.g. `--wait-until source_nexset_id`, `--wait-until samples`), or
+`--wait-until field=value` for an exact match (e.g.
+`--wait-until runtime_status=ACTIVE`). `--wait-timeout` (default 300s) and
+`--wait-interval` (default 5s) control the polling; timing out raises exit
+code `1` with the last observed value in the message, rather than hanging
+forever or silently returning stale state.
+
 ## Raw JSON body passthrough
 
 `create`/`update`-style commands (`sources`, `sinks`, `credentials`,
@@ -141,9 +151,10 @@ sink activates successfully (`status: ACTIVE`) and then sits in
 exist") only surfaces in the web UI's notification stream, not through
 this CLI. Create the table with the exact column set your nexset's
 `output_schema` implies before calling `sinks create`, or the run will
-silently stall. (`nexla triage resource-status sinks <sink_id>` and
-`nexla triage logs <flow_id>` will surface the JDBC error directly —
-see "Flow/log triage" below — instead of needing the web UI.)
+silently stall. (`nexla triage resource-status --resource-type sinks
+--resource-id <sink_id>` and `nexla triage logs <flow_id>` will surface
+the JDBC error directly — see "Flow/log triage" below — instead of
+needing the web UI.)
 
 `sinks create` now runs a pre-flight check for this itself when
 `--connector` is a known DB/JDBC connector and `--config` includes a
@@ -168,6 +179,18 @@ connector where the tree probe is known to be unreliable). `--dry-run`
 is unaffected either way — it always exits before any network call, this
 check included.
 
+**Supabase specifically always needs `--skip-table-check`.** Its tree
+probe (`nexla probe run --action tree --credential-id <id>`, drilling
+into `postgres` then `public`) bottoms out at the schema level and never
+returns table names at all — confirmed live, `--params '{"path":
+"public"}'` comes back `"nodes": []` regardless of what tables actually
+exist. That lands in the *second* outcome above (probe succeeds, table
+"not found" among zero returned names) — a hard failure, exit 2, not the
+softer warn-and-proceed branch — even when the table is genuinely there.
+Always pass `--skip-table-check` for Supabase sinks and verify the table
+exists yourself first (`psql`/the Supabase dashboard), rather than relying
+on this pre-flight check.
+
 ## `probe run`'s `--params` shape depends on the connector's `kind`
 
 `nexla probe run --action sample|tree --params '<json>'` takes a

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/src/nexla_cli/SKILL.md

@@ -98,6 +98,11 @@ asynchronously. Poll `nexla sources get <id>` (check `status`, and
 `source_nexset_id` once schema inference completes) instead of assuming
 the `create` response is the final state.
 
+`sources get`/`nexsets get`/`sinks get` support `--wait-until <field>`
+(polls until truthy) or `--wait-until field=value` (exact match), plus
+`--wait-timeout`/`--wait-interval` — use these instead of a hand-rolled
+polling loop, e.g. `nexla sources get <id> --wait-until source_nexset_id`.
+
 ## Inspecting the live API schema
 
 ```bash

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/src/nexla_cli/__init__.py

@@ -39,6 +39,7 @@ from .resources import (
     orgs,
     probe,
     sinks,
+    skill,
     sources,
     tools,
     toolsets,
@@ -169,6 +170,7 @@ for _mod in (
     users,
     notifications,
     triage,
+    skill,
 ):
     _wrap_app_commands(_mod.app)
     app.add_typer(_mod.app)

nexla_cli-0.2.1/src/nexla_cli/poll.py

@@ -0,0 +1,71 @@
+"""Shared ``--wait-until`` polling for ``get`` commands on resources that
+finish provisioning asynchronously.
+
+``sources create``/``sinks create`` auto-activate but don't block on
+activation (see AGENTS.md), and a transform's derived nexset takes a
+moment to get real samples -- every one of this session's own live runs
+hand-wrote a ``for i in ...; do ...; sleep N; done`` bash loop around
+``nexla <resource> get <id>`` to wait for readiness. This gives that loop
+a name instead of asking every caller to reinvent it.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any
+
+import typer
+
+from .errors import EXIT, CliError
+
+WAIT_TIMEOUT_OPT = typer.Option(300, "--wait-timeout", help="Max seconds to poll with --wait-until")
+WAIT_INTERVAL_OPT = typer.Option(5, "--wait-interval", help="Seconds between polls with --wait-until")
+
+
+def wait_until_option(example: str) -> Any:
+    """Build a ``--wait-until`` option with a resource-specific example.
+
+    A single shared example across sources/nexsets/sinks would show
+    ``source_nexset_id`` on `nexsets get`, where that field doesn't even
+    exist -- each caller passes the field that's actually relevant to it.
+    """
+    return typer.Option(
+        None,
+        "--wait-until",
+        help=f"Poll until this dotted field is truthy, or 'field=value' for an exact "
+        f"match (e.g. {example})",
+    )
+
+
+def _dotted_get(body: Any, field: str) -> Any:
+    cur = body
+    for part in field.split("."):
+        if not isinstance(cur, dict):
+            return None
+        cur = cur.get(part)
+    return cur
+
+
+def poll_until(fetch: Callable[[], Any], condition: str, timeout: int, interval: int) -> Any:
+    """Call ``fetch()`` repeatedly until ``condition`` is met or ``timeout`` elapses.
+
+    ``condition`` is a dotted field name (waits for a truthy/non-empty
+    value) or ``field=value`` for an exact string match. Raises
+    :class:`CliError` (exit ``EXIT.ERROR``) on timeout, including the last
+    observed value so the caller knows how far it got.
+    """
+    field, sep, expected = condition.partition("=")
+    deadline = time.monotonic() + timeout
+    while True:
+        body = fetch()
+        value = _dotted_get(body, field)
+        met = (str(value) == expected) if sep else bool(value)
+        if met:
+            return body
+        if time.monotonic() >= deadline:
+            raise CliError(
+                EXIT.ERROR,
+                f"timed out after {timeout}s waiting for {condition!r} (last value: {value!r})",
+            )
+        time.sleep(interval)

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/src/nexla_cli/resources/nexsets.py

@@ -10,7 +10,7 @@ import json as jsonlib
 
 import typer
 
-from .. import client, dryrun, output, validate
+from .. import client, dryrun, output, poll, validate
 
 app = typer.Typer(name="nexsets", help="Manage Nexla nexsets.", no_args_is_help=True)
 
@@ -56,13 +56,20 @@ def list_(
 
 
 @app.command("get")
-def get(ctx: typer.Context, nexset_id: int) -> None:
-    """Get one nexset, including samples and schema."""
-    output.emit(
-        client.request("GET", f"/nexla/nexsets/{nexset_id}"),
-        mode=output.ctx_mode(ctx),
-        fields=output.ctx_fields(ctx),
-    )
+def get(
+    ctx: typer.Context,
+    nexset_id: int,
+    wait_until: str | None = poll.wait_until_option("samples, or output_schema"),
+    wait_timeout: int = poll.WAIT_TIMEOUT_OPT,
+    wait_interval: int = poll.WAIT_INTERVAL_OPT,
+) -> None:
+    """Get one nexset, including samples and schema. `--wait-until samples` polls until non-empty."""
+
+    def fetch() -> object:
+        return client.request("GET", f"/nexla/nexsets/{nexset_id}")
+
+    body = poll.poll_until(fetch, wait_until, wait_timeout, wait_interval) if wait_until else fetch()
+    output.emit(body, mode=output.ctx_mode(ctx), fields=output.ctx_fields(ctx))
 
 
 @app.command("transform")

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/src/nexla_cli/resources/sinks.py

@@ -11,7 +11,7 @@ import json as jsonlib
 
 import typer
 
-from .. import client, dryrun, output, validate
+from .. import client, dryrun, output, poll, validate
 from ..errors import EXIT, CliError
 
 app = typer.Typer(name="sinks", help="Manage Nexla data sinks.", no_args_is_help=True)
@@ -160,13 +160,20 @@ def list_(
 
 
 @app.command("get")
-def get(ctx: typer.Context, sink_id: int) -> None:
-    """Get one sink by id."""
-    output.emit(
-        client.request("GET", f"/nexla/sinks/{sink_id}"),
-        mode=output.ctx_mode(ctx),
-        fields=output.ctx_fields(ctx),
-    )
+def get(
+    ctx: typer.Context,
+    sink_id: int,
+    wait_until: str | None = poll.wait_until_option("runtime_status=ACTIVE"),
+    wait_timeout: int = poll.WAIT_TIMEOUT_OPT,
+    wait_interval: int = poll.WAIT_INTERVAL_OPT,
+) -> None:
+    """Get one sink by id. `--wait-until runtime_status=ACTIVE` polls for a status change."""
+
+    def fetch() -> object:
+        return client.request("GET", f"/nexla/sinks/{sink_id}")
+
+    body = poll.poll_until(fetch, wait_until, wait_timeout, wait_interval) if wait_until else fetch()
+    output.emit(body, mode=output.ctx_mode(ctx), fields=output.ctx_fields(ctx))
 
 
 @app.command("create")

nexla_cli-0.2.1/src/nexla_cli/resources/skill.py

@@ -0,0 +1,56 @@
+"""`nexla skill install` — self-locating Claude Code skill installer.
+
+Claude Code only discovers skills at ``~/.claude/skills/<name>/SKILL.md``
+(global) or ``.claude/skills/<name>/SKILL.md`` (project-local) -- a file
+merely present inside an installed package isn't picked up automatically.
+Previously this required the user to figure out which install method
+(``uv tool``/``pipx``/npm-wrapped binary) put ``SKILL.md`` where, and
+hand-construct a glob path per method. ``importlib.resources`` already
+knows exactly where this package's own files live regardless of install
+method, so there's nothing to guess.
+
+Copies rather than symlinks: a symlink would be great for `uv tool`/`pipx`
+installs (auto-picks up future upgrades), but is useless for the
+PyInstaller-compiled binary (npm distribution), where the source path is
+an ephemeral extraction directory that's gone once the process exits. One
+behavior for every install method is simpler than branching on which one
+is in play; the tradeoff is re-running this command after an upgrade to
+pick up skill content changes.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(name="skill", help="Manage this CLI's Claude Code skill install.", no_args_is_help=True)
+
+
+@app.command("install")
+def install(
+    target: Path | None = typer.Option(
+        None,
+        help="Install directory. Default is the global ~/.claude/skills/nexla-cli; "
+        "pass .claude/skills/nexla-cli for a project-local install instead",
+    ),
+) -> None:
+    """Copy this package's SKILL.md and AGENTS.md to where Claude Code discovers it.
+
+    Both files, not just SKILL.md: SKILL.md itself points readers at
+    AGENTS.md for fuller explanations in a few places, so installing one
+    without the other leaves a dangling reference.
+    """
+    if target is None:
+        target = Path.home() / ".claude" / "skills" / "nexla-cli"
+    target.mkdir(parents=True, exist_ok=True)
+    for name in ("SKILL.md", "AGENTS.md"):
+        src = importlib.resources.files("nexla_cli") / name
+        # Explicit utf-8 on both ends: these files contain non-ASCII
+        # (em dashes) and the platform-default encoding read_text/
+        # write_text otherwise fall back to is cp1252 on Windows, which
+        # would raise or mangle bytes on that build.
+        (target / name).write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+    typer.echo(f"Installed skill to {target}")
+    typer.echo("Restart Claude Code (or start a new session) to pick it up.")

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/src/nexla_cli/resources/sources.py

@@ -10,7 +10,7 @@ import json as jsonlib
 
 import typer
 
-from .. import client, dryrun, output, validate
+from .. import client, dryrun, output, poll, validate
 
 app = typer.Typer(name="sources", help="Manage Nexla data sources.", no_args_is_help=True)
 
@@ -56,13 +56,20 @@ def list_(
 
 
 @app.command("get")
-def get(ctx: typer.Context, source_id: int) -> None:
-    """Get one source by id."""
-    output.emit(
-        client.request("GET", f"/nexla/sources/{source_id}"),
-        mode=output.ctx_mode(ctx),
-        fields=output.ctx_fields(ctx),
-    )
+def get(
+    ctx: typer.Context,
+    source_id: int,
+    wait_until: str | None = poll.wait_until_option("source_nexset_id, or status=ACTIVE"),
+    wait_timeout: int = poll.WAIT_TIMEOUT_OPT,
+    wait_interval: int = poll.WAIT_INTERVAL_OPT,
+) -> None:
+    """Get one source by id. `--wait-until source_nexset_id` polls until it appears."""
+
+    def fetch() -> object:
+        return client.request("GET", f"/nexla/sources/{source_id}")
+
+    body = poll.poll_until(fetch, wait_until, wait_timeout, wait_interval) if wait_until else fetch()
+    output.emit(body, mode=output.ctx_mode(ctx), fields=output.ctx_fields(ctx))
 
 
 @app.command("create")

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/src/nexla_cli/resources/triage.py

@@ -26,6 +26,8 @@ app = typer.Typer(
 _DRY_RUN_OPT = typer.Option(
     False, "--dry-run", help="Validate arguments locally against the tool's live schema; call nothing"
 )
+_FLOW_ID_ARG = typer.Argument(..., help="Flow ID")
+_RESOURCE_ID_OPT = typer.Option(..., help="ID of the source/nexset/sink named by --resource-type")
 
 
 def _args(**kwargs: object) -> dict[str, object]:
@@ -57,7 +59,7 @@ def errors(
 @app.command("status")
 def status(
     ctx: typer.Context,
-    flow_id: int,
+    flow_id: int = _FLOW_ID_ARG,
     run_id: int | None = typer.Option(None, help="Pin a specific run instead of the latest"),
     dry_run: bool = _DRY_RUN_OPT,
 ) -> None:
@@ -66,7 +68,12 @@ def status(
 
 
 @app.command("run")
-def run(ctx: typer.Context, flow_id: int, run_id: int, dry_run: bool = _DRY_RUN_OPT) -> None:
+def run(
+    ctx: typer.Context,
+    flow_id: int = _FLOW_ID_ARG,
+    run_id: int = typer.Argument(..., help="Run ID"),
+    dry_run: bool = _DRY_RUN_OPT,
+) -> None:
     """One flow run's execution timing (started_at/completed_at/duration_ms)."""
     _run(ctx, "get_flow_run", _args(flow_id=flow_id, run_id=run_id), dry_run)
 
@@ -74,7 +81,7 @@ def run(ctx: typer.Context, flow_id: int, run_id: int, dry_run: bool = _DRY_RUN_
 @app.command("metrics")
 def metrics(
     ctx: typer.Context,
-    flow_id: int,
+    flow_id: int = _FLOW_ID_ARG,
     from_date: str | None = typer.Option(None, help="YYYY-MM-DD, UTC, inclusive"),
     to_date: str | None = typer.Option(None, help="YYYY-MM-DD, UTC, exclusive"),
     granularity: str = typer.Option("daily", help="'daily' or 'monthly'"),
@@ -93,7 +100,7 @@ def metrics(
 def resource_status(
     ctx: typer.Context,
     resource_type: str = typer.Option(..., help="'sources' | 'nexsets' | 'sinks'"),
-    resource_id: int = typer.Option(...),
+    resource_id: int = _RESOURCE_ID_OPT,
     from_date: str | None = typer.Option(None, help="YYYY-MM-DD, UTC, inclusive"),
     to_date: str | None = typer.Option(None, help="YYYY-MM-DD, UTC, exclusive"),
     dry_run: bool = _DRY_RUN_OPT,
@@ -152,7 +159,7 @@ def notifications(
 @app.command("search")
 def search(
     ctx: typer.Context,
-    name: str,
+    name: str = typer.Argument(..., help="Name substring to search for"),
     limit: int = typer.Option(10, help="Max hits"),
     dry_run: bool = _DRY_RUN_OPT,
 ) -> None:
@@ -163,7 +170,7 @@ def search(
 @app.command("logs")
 def logs(
     ctx: typer.Context,
-    flow_id: int,
+    flow_id: int = _FLOW_ID_ARG,
     run_id: int | None = typer.Option(None, help="Pin to one run; omit is noisy across all runs"),
     severity: str | None = typer.Option(None, help="ERROR|WARNING|INFO"),
     search: str | None = typer.Option(None, help="Free-text substring match on log message bodies"),
@@ -193,7 +200,7 @@ def logs(
 def quarantine(
     ctx: typer.Context,
     resource_type: str = typer.Option(..., help="'sources' | 'nexsets' | 'sinks'"),
-    resource_id: int = typer.Option(...),
+    resource_id: int = _RESOURCE_ID_OPT,
     sample_size: int = typer.Option(10, help="How many rejected records to return"),
     dry_run: bool = _DRY_RUN_OPT,
 ) -> None:

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/tests/test_contract.py

@@ -32,8 +32,10 @@ pytestmark = pytest.mark.skipif(
 
 # `schema` is Phase 3's own callback-only sub-app, not one of the 17
 # resource modules the overview plan's surface table covers -- it has no
-# `/nexla/schema` route to check against.
-_NON_RESOURCE_GROUPS = {"schema"}
+# `/nexla/schema` route to check against. `skill` is a purely local
+# filesystem operation (installs SKILL.md to ~/.claude/skills/) that makes
+# no HTTP call at all -- same reasoning, no live route to check.
+_NON_RESOURCE_GROUPS = {"schema", "skill"}
 
 # Per the overview plan's surface table: these resources are fully stubbed
 # (every route 501s) and their sub-router is deliberately hidden from

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/tests/test_nexsets.py

@@ -28,6 +28,23 @@ def test_get(runner: CliRunner, cli_app, respx_mock: respx.MockRouter) -> None:
     assert route.called
 
 
+def test_get_wait_until_polls_until_samples_appear(
+    runner: CliRunner, cli_app, respx_mock: respx.MockRouter, monkeypatch
+) -> None:
+    monkeypatch.setattr("nexla_cli.poll.time.sleep", lambda s: None)
+    route = respx_mock.get(f"{BASE_URL}/nexla/nexsets/1").mock(
+        side_effect=[
+            httpx.Response(200, json={"id": 1, "samples": []}),
+            httpx.Response(200, json={"id": 1, "samples": [{"x": 1}]}),
+        ]
+    )
+    result = runner.invoke(
+        cli_app, ["nexsets", "get", "1", "--wait-until", "samples", "--wait-interval", "0"]
+    )
+    assert result.exit_code == 0
+    assert route.call_count == 2
+
+
 def test_transform(runner: CliRunner, cli_app, respx_mock: respx.MockRouter) -> None:
     route = respx_mock.post(f"{BASE_URL}/nexla/nexsets/1/transform").mock(
         return_value=httpx.Response(201, json={"id": 2, "name": "derived"})

nexla_cli-0.2.1/tests/test_poll.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import pytest
+
+from nexla_cli.errors import CliError
+from nexla_cli.poll import poll_until
+
+
+def test_poll_until_truthy_field_returns_immediately() -> None:
+    body = {"id": 1, "source_nexset_id": 42}
+    assert poll_until(lambda: body, "source_nexset_id", timeout=5, interval=0) == body
+
+
+def test_poll_until_truthy_field_waits_for_it(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = iter([{"source_nexset_id": None}, {"source_nexset_id": None}, {"source_nexset_id": 7}])
+    sleeps: list[float] = []
+    monkeypatch.setattr("nexla_cli.poll.time.sleep", lambda s: sleeps.append(s))
+    result = poll_until(lambda: next(calls), "source_nexset_id", timeout=5, interval=1)
+    assert result == {"source_nexset_id": 7}
+    assert sleeps == [1, 1]
+
+
+def test_poll_until_exact_match(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = iter([{"runtime_status": "IDLE"}, {"runtime_status": "ACTIVE"}])
+    monkeypatch.setattr("nexla_cli.poll.time.sleep", lambda s: None)
+    result = poll_until(lambda: next(calls), "runtime_status=ACTIVE", timeout=5, interval=1)
+    assert result == {"runtime_status": "ACTIVE"}
+
+
+def test_poll_until_dotted_field() -> None:
+    body = {"status": {"phase": "done"}}
+    assert poll_until(lambda: body, "status.phase=done", timeout=5, interval=1) == body
+
+
+def test_poll_until_times_out(monkeypatch: pytest.MonkeyPatch) -> None:
+    ticks = iter([0.0, 0.0, 10.0])  # deadline computed from the first tick, exceeded on the third
+    monkeypatch.setattr("nexla_cli.poll.time.monotonic", lambda: next(ticks))
+    monkeypatch.setattr("nexla_cli.poll.time.sleep", lambda s: None)
+    with pytest.raises(CliError) as exc_info:
+        poll_until(lambda: {"source_nexset_id": None}, "source_nexset_id", timeout=5, interval=1)
+    assert exc_info.value.code == 1
+    assert "timed out after 5s" in exc_info.value.message

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/tests/test_sinks.py

@@ -35,6 +35,24 @@ def test_get(runner: CliRunner, cli_app, respx_mock: respx.MockRouter) -> None:
     assert route.called
 
 
+def test_get_wait_until_exact_match(
+    runner: CliRunner, cli_app, respx_mock: respx.MockRouter, monkeypatch
+) -> None:
+    monkeypatch.setattr("nexla_cli.poll.time.sleep", lambda s: None)
+    route = respx_mock.get(f"{BASE_URL}/nexla/sinks/1").mock(
+        side_effect=[
+            httpx.Response(200, json={"id": 1, "runtime_status": "IDLE"}),
+            httpx.Response(200, json={"id": 1, "runtime_status": "ACTIVE"}),
+        ]
+    )
+    result = runner.invoke(
+        cli_app,
+        ["sinks", "get", "1", "--wait-until", "runtime_status=ACTIVE", "--wait-interval", "0"],
+    )
+    assert result.exit_code == 0
+    assert route.call_count == 2
+
+
 def test_create(runner: CliRunner, cli_app, respx_mock: respx.MockRouter) -> None:
     route = respx_mock.post(f"{BASE_URL}/nexla/sinks").mock(
         return_value=httpx.Response(201, json={"id": 2, "name": "new-sink"})

nexla_cli-0.2.1/tests/test_skill.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+
+def test_install_default_target_uses_home(
+    runner: CliRunner, cli_app, monkeypatch, tmp_path: Path
+) -> None:
+    import nexla_cli
+
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    result = runner.invoke(cli_app, ["skill", "install"])
+    assert result.exit_code == 0
+    installed_dir = tmp_path / ".claude" / "skills" / "nexla-cli"
+    packaged_dir = Path(nexla_cli.__file__).parent
+    for name in ("SKILL.md", "AGENTS.md"):
+        assert (installed_dir / name).read_text(encoding="utf-8") == (
+            packaged_dir / name
+        ).read_text(encoding="utf-8")
+
+
+def test_install_explicit_target(runner: CliRunner, cli_app, tmp_path: Path) -> None:
+    target = tmp_path / "custom"
+    result = runner.invoke(cli_app, ["skill", "install", "--target", str(target)])
+    assert result.exit_code == 0
+    assert (target / "SKILL.md").is_file()
+    assert (target / "AGENTS.md").is_file()

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/tests/test_sources.py

@@ -38,6 +38,24 @@ def test_get(runner: CliRunner, cli_app, respx_mock: respx.MockRouter) -> None:
     assert "s1" in result.stdout
 
 
+def test_get_wait_until_polls_until_field_appears(
+    runner: CliRunner, cli_app, respx_mock: respx.MockRouter, monkeypatch
+) -> None:
+    monkeypatch.setattr("nexla_cli.poll.time.sleep", lambda s: None)
+    route = respx_mock.get(f"{BASE_URL}/nexla/sources/1").mock(
+        side_effect=[
+            httpx.Response(200, json={"id": 1, "source_nexset_id": None}),
+            httpx.Response(200, json={"id": 1, "source_nexset_id": 42}),
+        ]
+    )
+    result = runner.invoke(
+        cli_app, ["sources", "get", "1", "--wait-until", "source_nexset_id", "--wait-interval", "0"]
+    )
+    assert result.exit_code == 0
+    assert route.call_count == 2
+    assert "42" in result.stdout
+
+
 def test_get_not_found(runner: CliRunner, cli_app, respx_mock: respx.MockRouter) -> None:
     respx_mock.get(f"{BASE_URL}/nexla/sources/99").mock(
         return_value=httpx.Response(404, json={"detail": {"error": "not_found"}})

{nexla_cli-0.2.0 → nexla_cli-0.2.1}/uv.lock

@@ -280,7 +280,7 @@ wheels = [
 
 [[package]]
 name = "nexla-cli"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

nexla_cli-0.2.0/npm/README.md

@@ -1,27 +0,0 @@
-# nexla-cli (npm wrapper)
-
-Thin npm package that installs the prebuilt `nexla` binary — no Python
-required. `postinstall` (`scripts/install.js`) downloads the binary matching
-the current OS/arch from the GitHub release tagged `v<package version>`;
-`bin/nexla.js` execs it and forwards argv/stdio/exit code.
-
-## Cutting a release
-
-1. Bump the version in both `pyproject.toml` and `npm/package.json` — they
-   must match, since `scripts/install.js` derives the release tag from
-   `npm/package.json`'s version.
-2. `git tag vX.Y.Z && git push --tags` — this triggers
-   `.github/workflows/release-binaries.yml`, which builds binaries for
-   macOS (arm64), Linux (x64), and Windows (x64) via PyInstaller and
-   attaches them to the GitHub release.
-3. Once the release assets are up, publish the npm wrapper:
-   ```bash
-   cd npm && npm publish
-   ```
-
-Supported platforms: `darwin-arm64`, `linux-x64`, `win32-x64` (see
-`scripts/install.js`'s `ASSETS` map — add an entry there and a matching
-matrix row in the workflow to support more, e.g. Intel Mac was dropped
-from the matrix due to GitHub's shrinking `macos-13` runner capacity;
-re-add a `macos-13` row + a `darwin-x64` ASSETS entry if that's needed
-again).