Metadata-Version: 2.4
Name: borescope
Version: 0.1.0.dev1
Summary: A natural shell for debugging Juju Kubernetes workload containers via Pebble
Project-URL: Homepage, https://github.com/tonyandrewmeyer/borescope
Project-URL: Repository, https://github.com/tonyandrewmeyer/borescope
Project-URL: Bug Tracker, https://github.com/tonyandrewmeyer/borescope/issues
Author-email: Tony Meyer <borescope@aotearoa.dev>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: charm,debugging,juju,kubernetes,pebble,shell
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: ops<4,>=2.0.0
Requires-Dist: pebble-shimmer>=1.0.0b2
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# borescope

A natural shell for debugging Juju Kubernetes **workload** containers.

Kubernetes charm workload containers usually run a [rock](https://documentation.ubuntu.com/rockcraft/)
with no shell — so when something breaks, `juju ssh --container=workload …` drops
you nowhere useful. borescope gives you a prompt that *feels* like `bash` but talks to
the container's [Pebble](https://documentation.ubuntu.com/pebble/) instead of a real shell:

```console
$ borescope myapp/0
pebble:/# ls /var/log/myapp
pebble:/# tail -f /var/log/myapp/error.log
pebble:/# services
pebble:/# logs --follow myapp
pebble:/# plan
pebble:/# exit
```

No setup ceremony: borescope picks up your current Juju controller/model and uses your
existing `juju` authority — if you can `juju ssh` to the unit, borescope works; if you
can't, it fails the same way.

## Install

> v1 is under active development. For now, from a checkout:

```console
uv tool install .        # or: pipx install .
```

## Usage

```console
borescope <unit>                       # default (first) workload container
borescope <unit> --container=<name>    # a specific workload container
borescope --model <model> <unit>
borescope <unit> --command "services"  # one-shot, no REPL (for scripts)
borescope <unit> --snapshot            # dump container state as JSON
```

## How it works

borescope is three thin, independently-testable layers:

- **Transport** — talks to a Pebble. The primary backend (`CliTransport`) reaches the
  workload's Pebble *through the charm container* — `juju ssh <unit>` (the charm
  container always has a shell) pointed at the workload's socket, which Juju mounts
  there at `/charm/containers/<name>/pebble.socket`. This works even against rocks
  with **no shell** (the shell lives in the charm container, not the rock) and stays
  entirely within your Juju authority — no `kubectl` or cluster-admin. It drives
  `pebble` via [shimmer](https://github.com/tonyandrewmeyer/shimmer) (a drop-in
  `ops.pebble.Client` over the Pebble CLI). When the Pebble socket is directly
  reachable (running inside the charm, or a local Pebble), `SocketTransport` uses the
  real `ops.pebble.Client` HTTP API instead.
- **Discovery** — turns a unit reference into the right Pebble: confirms the unit,
  reads the charm's `metadata.yaml` for workload container names, and sanity-checks
  the container is alive. Everything uses your Juju model access — no `kubectl` /
  cluster-admin.
- **Shell** — a small REPL: `cd`/`pwd`, path-aware tab completion, history, and a
  minimal command set. Pebble's own vocabulary (`services`, `logs`, `plan`, …) is
  first-class, not hidden behind a `pebble` prefix. For anything else, `exec <cmd>`
  runs a binary that's already in the container.

## Scope

borescope is for **Kubernetes** charms (which run Pebble). Machine charms already have
a real shell and are out of scope. It deliberately ships a *minimal* command set and
grows on request — if a tool exists in the container, reach it with `exec`.
