borescope documentation

A natural shell for debugging Juju Kubernetes workload containers, through Pebble, with your existing Juju authority.

This documentation follows the Diataxis framework, organising content by what you need: learning, solving problems, looking things up, or understanding how the system works.

Start here

New to borescope? Work through the tutorial. It takes you from install to poking around a live container in about ten minutes.
Have a unit in mind? Jump to Connect to a unit to pick the right container, model, or controller.
Looking something up? The CLI reference lists every flag, and the command reference covers every built-in command.
Want to know how it works? Start with How borescope works and How it reaches Pebble.

Tutorial

Debug your first container

A guided walkthrough from installation to reading logs, services, and the plan on a live workload container. No prior experience required.

How-to guides

Connect to a unit

Target the right workload container, model, and controller, and understand what borescope does when you don’t say.

Run inside the charm container

Use --here from a charm hook or juju ssh session to talk to a mounted Pebble socket directly, or point at any socket with --socket.

Run one command (no REPL)

Drive a single command with --command, or pipe a script in on stdin, for aliases, CI, and automation.

Copy files in and out

Pull a log or config file out of a shell-less container, or push a patched file back in, with pull and push.

Capture a state snapshot

Produce a stable JSON document of services, plan, checks, notices, and recent logs, for bug reports and tooling.

Reference

CLI reference

Every command-line argument, the modes they select, and exit codes.

Command reference

Every built-in command (shell, files, Pebble-native), plus the exec escape hatch.