Shimmer — a shiny Pebble client

A 100% compatible, drop-in replacement for ops.pebble.Client that drives Pebble through its CLI instead of the unix socket — for environments where the socket isn't reachable (such as a Rock or a Juju container).

_{The same deploy-and-verify routine run over ops.pebble.Client (unix socket, left) and shimmer.PebbleCliClient (CLI, right) — identical results.}

Overview

PebbleCliClient implements the same interface as ops.pebble.Client: same method signatures, same return types, same raised exceptions. Under the hood it translates each call into a pebble CLI command, parses the output back into the same Python objects ops returns, and maps CLI errors onto the matching exceptions. The contract is parity — code written against ops.pebble.Client should run unchanged against Shimmer.

Installation

# From PyPI
uv pip install pebble-shimmer

# Development version
git clone https://github.com/tonyandrewmeyer/shimmer
cd shimmer
uv pip install -e .

Usage

Construct the client, then use it exactly like ops.pebble.Client — the methods, arguments, return types, and exceptions are the same:

from shimmer import PebbleCliClient as Client

client = Client()
client.replan_services()
for service in client.get_services():
    print(service.name, service.current.value)

The whole point is that there's nothing new to learn: the full method surface is documented by ops.pebble.Client. Swapping ops.pebble.Client for shimmer.PebbleCliClient is the only change.

The constructor is where Shimmer differs, since it talks to a binary rather than a socket:

client = Client(
    socket_path="/var/lib/pebble/default/.pebble.socket",  # sets PEBBLE / PEBBLE_SOCKET
    pebble_binary="/snap/bin/pebble",  # path to the pebble binary (default: "pebble")
    timeout=5.0,  # default per-command timeout in seconds
)

socket_path doesn't open a socket — it points Shimmer at the daemon by setting PEBBLE (its parent directory) and PEBBLE_SOCKET for the CLI. For drop-in parity the constructor also accepts opener and base_url, but those only configure the socket transport, so Shimmer accepts and ignores them. The ops.pebble exceptions are re-exported from shimmer for convenience, but they are the same objects, so except ops.pebble.APIError keeps working too.

Demo and verification

The GIF above is a recording of demo.md — a Showboat document that runs one deploy-and-verify routine against the real socket client, then the same code against Shimmer, and diffs the two outputs to prove they're identical. It's reproducible:

uv run python demo.py            # rebuild demo.md (verifies parity live)
uv run python demo.py --record   # re-record demo.cast (needs tmux + asciinema)
agg demo.cast demo.gif           # regenerate the GIF from the cast

Parity is also exercised in CI by tests/integration/test_parity.py, which runs the same operations through both clients and asserts equal results.

Limitations and parity notes

CLI invocation is the source of every limitation here — each call spawns a pebble process, so there's more per-call overhead than the socket transport, and some streaming is buffered rather than incremental.

A few methods can't fully match the socket client:

• replan_services(), start_services(), stop_services(), and restart_services() return the change ID only when no timeout is set.
• notify() supports custom notices only (Pebble's CLI only exposes pebble notify for custom notices).
• abort_change() raises NotImplementedError: the Pebble CLI exposes no command to abort a change, so there is no way to back this through the CLI.
• get_warnings() works by reading pebble warnings --format json (Pebble surfaces warnings as notices of type warning) and mapping the result back to ops.pebble.Warning, so it stays drop-in with ops.pebble.Client. ack_warnings() still raises NotImplementedError: pebble okay acks by local CLI state, not by timestamp, so ops's timestamp semantics cannot be reproduced.

get_system_info(), get_services(), get_checks(), list_files(), get_changes(), get_change(), get_notices(), get_notice(), get_warnings(), and get_identities() use Pebble's structured --format json output, so they return the same rich data as ops.pebble.Client (change kind/tasks/err, check thresholds, real file ownership, local identity user IDs). This requires Pebble v1.32.0 or later (which added --format to pebble version).

Comparison with ops.pebble.Client

Troubleshooting

Pebble binary not found — pass the full path: Client(pebble_binary="/snap/bin/pebble").

Connection error — confirm the daemon is up and PEBBLE points at its home directory (or pass socket_path=); check pebble version.

See the commands Shimmer runs — enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

More

• CONTRIBUTING.md — contribution guidelines
• CHANGELOG.md — version history
• Related: ops · pebble · juju · charmcraft · rockcraft