posit-cli 0.1.0__tar.gz

posit_cli-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,49 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+      - uses: extractions/setup-just@v4
+      # Fail fast if uv.lock has drifted from pyproject.toml.
+      - run: uv lock --locked
+      - run: just lint
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.8"
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: extractions/setup-just@v4
+      - run: just test ${{ matrix.python-version }}
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+      - uses: extractions/setup-just@v4
+      - run: just build
+      - run: just smoke

posit_cli-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,37 @@
+name: Release
+on:
+  push:
+    tags:
+      - "v*.*.*"
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v9.0.0
+      - uses: extractions/setup-just@v4
+      - name: assert tag matches pyproject version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          ver="$(just version)"
+          if [ "$TAG" != "v$ver" ]; then
+            echo "::error::tag '${TAG}' does not match pyproject version 'v${ver}'"
+            exit 1
+          fi
+      - name: assert tag is on main
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          if ! git merge-base --is-ancestor HEAD origin/main; then
+            echo "::error::tag '${TAG}' points to a commit that is not on main"
+            exit 1
+          fi
+      - run: just build
+      - run: just smoke
+      - uses: pypa/gh-action-pypi-publish@release/v1

posit_cli-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+# roborev snapshots
+/.roborev/

posit_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,40 @@
+# posit-cli
+
+A single, friendly CLI — `posit` — for working with Posit Connect, in the spirit of
+[`gh`](https://cli.github.com/). Distribution name `posit-cli`, import package `posit_cli`,
+executable `posit`.
+
+- `posit connect api <path>` is a `gh api`-style raw REST client (OAuth-authenticated).
+- Other `posit connect` commands (`login`, `deploy`, `add`, `list`, ...) are mounted dynamically
+  from rsconnect-python's Click group, so they come for free and track upstream.
+
+See `architecture-rsconnect-not-posit-sdk` in memory for why we wrap rsconnect-python (not
+posit-sdk) and the OAuth-release gotcha.
+
+## Design principles
+
+- **Idiomatic first; deviate from rsconnect-python when it helps.** We deliberately built a
+  separate project (not a patch to rsconnect) so we can make breaking changes freely. The CLI
+  surface is *ours*. When rsconnect-python's naming or behavior is awkward, prefer what
+  mainstream CLIs (especially `gh`, plus `curl`/`kubectl`) do, and what reads clearly to both
+  humans and coding agents. Don't stay coupled to rsconnect's details for their own sake.
+  - Example: rsconnect exposes `--insecure`/`-i` to skip TLS verification. We renamed it to
+    `--no-tls-verify` (more explicit; "insecure" is vague) and freed the `-i` short flag so it
+    can later mean `--include` as it does in `gh api`.
+- **`posit connect api` tracks `gh api` conventions** where they make sense for Connect. Where a
+  `gh` idiom doesn't fit Connect (e.g. `{owner}/{repo}` path placeholders, GraphQL), drop it
+  rather than fake it.
+- **Mounted rsconnect commands stay as-is** unless we have a specific reason to override one —
+  the value of mounting is that they track upstream. Overriding a name means owning it.
+
+## Conventions
+
+- Keep credential flags consistent with the mounted rsconnect commands where they overlap
+  (`-n/--name`, `-s/--server`, `-k/--api-key`, env `CONNECT_SERVER`/`CONNECT_API_KEY`/
+  `CONNECT_INSECURE`) so the whole `posit connect` surface feels uniform — even when we rename
+  the flag, keep honoring the shared env var.
+- `posit connect api` uses rsconnect's *internal* client (`RSConnectExecutor` ->
+  `RSConnectClient`), which has no stability contract. `tests/test_rsconnect_contract.py` guards
+  the surface we depend on; pin the rsconnect version and re-verify on bumps.
+
+See `RELEASE.md` for how to cut a release to PyPI.

posit_cli-0.1.0/Justfile

@@ -0,0 +1,38 @@
+# posit-cli task runner. Run `just --list` to see recipes.
+
+# Run the test suite against a single Python version (default 3.13)
+test py="3.13":
+    uv run --python {{py}} --extra test pytest tests
+
+# Check formatting and lint
+lint:
+    uv run --extra lint ruff format --check
+    uv run --extra lint ruff check
+
+# Auto-format and apply lint fixes
+fmt:
+    uv run --extra lint ruff format
+    uv run --extra lint ruff check --fix
+
+# Build wheel + sdist
+build:
+    uv build
+
+# Smoke-test the most recently built wheel (no project install)
+smoke:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    WHL=$(ls -t dist/*.whl | head -1)
+    uv run --no-project --with "$WHL" posit --help
+
+# Install the most recently built wheel into the active environment
+install: build
+    uv pip install "$(ls -t dist/*.whl | head -1)"
+
+# Print the current version
+version:
+    @uv version --short
+
+# Remove build/test artifacts
+clean:
+    rm -rf .coverage .pytest_cache .ruff_cache build dist *.egg-info

posit_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Posit Software, PBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

posit_cli-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: posit-cli
+Version: 0.1.0
+Summary: A single, friendly command-line interface for Posit Connect, in the spirit of gh.
+Author: Posit Software, PBC
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: click>=8.0
+Requires-Dist: jq>=1.4
+Requires-Dist: keyring>=23.0
+Requires-Dist: rsconnect-python<2,>=1.30
+Provides-Extra: lint
+Requires-Dist: ruff>=0.6; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# posit-cli
+
+A friendly command-line interface for Posit products, in the spirit of [`gh`](https://cli.github.com/).
+
+```console
+$ posit connect login https://connect.example.com             # OAuth, tokens in your OS keyring
+$ posit connect api v1/user -q .username                      # gh-api-style raw request
+$ posit connect deploy streamlit ./my-app                     # everything rsconnect can do
+```
+
+This project is in early-stage development and so far only supports Posit Connect's APIs.
+
+## Installation
+
+`posit-cli` isn't on PyPI yet. Install the latest version straight from GitHub
+with [`uv`](https://docs.astral.sh/uv/):
+
+```console
+uv tool install git+https://github.com/posit-dev/posit-cli.git
+```
+
+If you authenticate to GitHub over SSH, use the `git+ssh://` form instead (uv
+requires the `git@` username):
+
+```console
+uv tool install git+ssh://git@github.com/posit-dev/posit-cli.git
+```
+
+Either way this puts the `posit` executable on your `PATH`. To upgrade later, run
+`uv tool upgrade posit-cli`. See uv's
+[Git authentication docs](https://docs.astral.sh/uv/concepts/authentication/git/)
+for tokens and other hosts.
+
+## Getting started
+
+**1. Log in.** Point `posit` at your Connect server and authenticate. This runs
+an OAuth 2.1 flow in your browser and saves the tokens in your OS keyring, so
+you only do it once per server:
+
+```console
+$ posit connect login https://connect.example.com
+```
+
+**2. Try a request.** Confirm you're connected by asking Connect who you are:
+
+```console
+$ posit connect api v1/user -q .username
+```
+
+**3. Deploy something.** Anything `rsconnect` can deploy, `posit` can too:
+
+```console
+$ posit connect deploy streamlit ./my-app
+```
+
+That's it — from here, explore `posit connect --help` for the full command set.
+
+## Authentication
+
+`posit connect login` runs an OAuth 2.1 flow and stores tokens in your OS
+keyring; `posit connect api` and the deploy commands reuse those credentials
+automatically (including token refresh). You can also point at a server ad hoc
+with `--server`/`CONNECT_SERVER` and `--api-key`/`CONNECT_API_KEY`.
+
+## `posit connect api`
+
+A `gh api`-style raw REST client, authenticated with your saved credentials.
+`PATH` is relative to the Connect API root (the `/__api__` prefix is added for
+you):
+
+```console
+$ posit connect api v1/user                          # GET, pretty-printed JSON
+$ posit connect api v1/user -q .username             # filter with a jq expression
+$ posit connect api "v1/content?limit=3" -q '.[].name'
+```
+
+`-q`/`--jq` runs the response through [jq](https://jqlang.github.io/jq/), like
+`gh api --jq`: string results print unquoted, one per line.
+
+`-i`/`--include` prepends the HTTP status line and response headers to the
+output (handy for inspecting rate limits, request IDs, or the server version):
+
+```console
+$ posit connect api v1/user -i
+```
+
+`--paginate` (GET only) follows Connect's pagination and prints all pages'
+results combined. It handles both of Connect's pagination styles — the
+cursor style (e.g. `v1/audit_logs`) and the page-number style (e.g.
+`v1/users`, `v1/groups`) — and leaves unpaginated endpoints unchanged:
+
+```console
+$ posit connect api v1/users --paginate -q 'length'   # count every user
+```
+
+`PATH` may also be a full URL on the configured server — convenient for pasting
+a `paging.next` link straight back in. A URL for a different host is rejected.
+
+### Query parameters vs. request body
+
+Like `gh api`, `-f`/`-F` fields default to a **POST request body** (adding any
+field flips the method to POST unless you pass `-X`). To send **query
+parameters** on a read, put them in the path or force `GET`:
+
+```console
+$ posit connect api "v1/users?page_size=5"   # query params in the path
+$ posit connect api v1/users -X GET -f page_size=5          # or force GET
+$ posit connect api v1/content -f name=my-app              # POST body (creates content)
+```
+
+## `posit connect *`
+
+`posit` wraps [`rsconnect-python`](https://github.com/posit-dev/rsconnect-python):
+it re-exposes the full `rsconnect` command set under `posit connect`, in addition to the `api` utility.
+
+## Using `posit` with Claude Code
+
+This repo ships a skill (at [`skills/posit-cli/`](skills/posit-cli/)) that teaches
+coding agents to drive `posit` — auth, `posit connect api`, and deploys. Install
+it with the [`skills`](https://www.skills.sh/) CLI:
+
+```console
+npx skills add posit-dev/posit-cli
+```

posit_cli-0.1.0/README.md

@@ -0,0 +1,124 @@
+# posit-cli
+
+A friendly command-line interface for Posit products, in the spirit of [`gh`](https://cli.github.com/).
+
+```console
+$ posit connect login https://connect.example.com             # OAuth, tokens in your OS keyring
+$ posit connect api v1/user -q .username                      # gh-api-style raw request
+$ posit connect deploy streamlit ./my-app                     # everything rsconnect can do
+```
+
+This project is in early-stage development and so far only supports Posit Connect's APIs.
+
+## Installation
+
+`posit-cli` isn't on PyPI yet. Install the latest version straight from GitHub
+with [`uv`](https://docs.astral.sh/uv/):
+
+```console
+uv tool install git+https://github.com/posit-dev/posit-cli.git
+```
+
+If you authenticate to GitHub over SSH, use the `git+ssh://` form instead (uv
+requires the `git@` username):
+
+```console
+uv tool install git+ssh://git@github.com/posit-dev/posit-cli.git
+```
+
+Either way this puts the `posit` executable on your `PATH`. To upgrade later, run
+`uv tool upgrade posit-cli`. See uv's
+[Git authentication docs](https://docs.astral.sh/uv/concepts/authentication/git/)
+for tokens and other hosts.
+
+## Getting started
+
+**1. Log in.** Point `posit` at your Connect server and authenticate. This runs
+an OAuth 2.1 flow in your browser and saves the tokens in your OS keyring, so
+you only do it once per server:
+
+```console
+$ posit connect login https://connect.example.com
+```
+
+**2. Try a request.** Confirm you're connected by asking Connect who you are:
+
+```console
+$ posit connect api v1/user -q .username
+```
+
+**3. Deploy something.** Anything `rsconnect` can deploy, `posit` can too:
+
+```console
+$ posit connect deploy streamlit ./my-app
+```
+
+That's it — from here, explore `posit connect --help` for the full command set.
+
+## Authentication
+
+`posit connect login` runs an OAuth 2.1 flow and stores tokens in your OS
+keyring; `posit connect api` and the deploy commands reuse those credentials
+automatically (including token refresh). You can also point at a server ad hoc
+with `--server`/`CONNECT_SERVER` and `--api-key`/`CONNECT_API_KEY`.
+
+## `posit connect api`
+
+A `gh api`-style raw REST client, authenticated with your saved credentials.
+`PATH` is relative to the Connect API root (the `/__api__` prefix is added for
+you):
+
+```console
+$ posit connect api v1/user                          # GET, pretty-printed JSON
+$ posit connect api v1/user -q .username             # filter with a jq expression
+$ posit connect api "v1/content?limit=3" -q '.[].name'
+```
+
+`-q`/`--jq` runs the response through [jq](https://jqlang.github.io/jq/), like
+`gh api --jq`: string results print unquoted, one per line.
+
+`-i`/`--include` prepends the HTTP status line and response headers to the
+output (handy for inspecting rate limits, request IDs, or the server version):
+
+```console
+$ posit connect api v1/user -i
+```
+
+`--paginate` (GET only) follows Connect's pagination and prints all pages'
+results combined. It handles both of Connect's pagination styles — the
+cursor style (e.g. `v1/audit_logs`) and the page-number style (e.g.
+`v1/users`, `v1/groups`) — and leaves unpaginated endpoints unchanged:
+
+```console
+$ posit connect api v1/users --paginate -q 'length'   # count every user
+```
+
+`PATH` may also be a full URL on the configured server — convenient for pasting
+a `paging.next` link straight back in. A URL for a different host is rejected.
+
+### Query parameters vs. request body
+
+Like `gh api`, `-f`/`-F` fields default to a **POST request body** (adding any
+field flips the method to POST unless you pass `-X`). To send **query
+parameters** on a read, put them in the path or force `GET`:
+
+```console
+$ posit connect api "v1/users?page_size=5"   # query params in the path
+$ posit connect api v1/users -X GET -f page_size=5          # or force GET
+$ posit connect api v1/content -f name=my-app              # POST body (creates content)
+```
+
+## `posit connect *`
+
+`posit` wraps [`rsconnect-python`](https://github.com/posit-dev/rsconnect-python):
+it re-exposes the full `rsconnect` command set under `posit connect`, in addition to the `api` utility.
+
+## Using `posit` with Claude Code
+
+This repo ships a skill (at [`skills/posit-cli/`](skills/posit-cli/)) that teaches
+coding agents to drive `posit` — auth, `posit connect api`, and deploys. Install
+it with the [`skills`](https://www.skills.sh/) CLI:
+
+```console
+npx skills add posit-dev/posit-cli
+```

posit_cli-0.1.0/RELEASE.md

@@ -0,0 +1,22 @@
+# Releasing
+
+Follow these steps to publish a new version to PyPI:
+
+1. Bump `version` in `pyproject.toml`.
+2. Run `uv lock` if the bump changed any dependency. CI fails the build if `uv.lock` has drifted.
+3. Commit the change and merge it to `main`.
+4. Tag the merged commit on `main` as `vX.Y.Z`. The tag must match the `pyproject.toml` version
+   exactly.
+5. Push the tag. This triggers `.github/workflows/release.yaml`.
+
+The release workflow checks the tag against `pyproject.toml` and against `main`, builds the
+wheel and sdist, smoke-tests the wheel, then publishes to PyPI through GitHub's OIDC
+trusted-publisher flow. No PyPI token is stored in this repo.
+
+## One-time setup for a new repo
+
+- Create a `release` environment under the repo's Settings > Environments, with required
+  reviewers. The `publish` job runs under this environment; without required reviewers, any tag
+  push publishes to PyPI immediately with no human gate.
+- Configure a trusted publisher for `posit-cli` on PyPI with: Owner `posit-dev`, Repository name
+  `posit-cli`, Workflow name `release.yaml`, Environment name `release`.

posit_cli-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "posit-cli"
+version = "0.1.0"
+description = "A single, friendly command-line interface for Posit Connect, in the spirit of gh."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Posit Software, PBC" }]
+dependencies = [
+    # posit-cli reuses rsconnect-python's *internal* API (RSConnectExecutor,
+    # RSConnectClient). These have no stability contract, so re-verify the internals
+    # on bumps. See tests/test_rsconnect_contract.py.
+    "rsconnect-python>=1.30,<2",
+    # rsconnect imports `keyring` optionally; we depend on it directly so OAuth
+    # tokens land in the OS keyring.
+    "keyring>=23.0",
+    "click>=8.0",
+    # jq bindings power `posit connect api --jq`, mirroring `gh api --jq`.
+    "jq>=1.4",
+]
+
+[project.scripts]
+posit = "posit_cli.__main__:cli"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+lint = ["ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/posit_cli"]
+
+[tool.ruff]
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]