Jockey is a CLI tool for querying Juju model data with concise filter expressions. It currently supports querying units and machines and can filter them using related object values (applications, charms, hostnames, IPs, and availability zones).

Jockey relies on this model of Juju objects and how they are related:

---
title: Juju object relationships
---
flowchart LR
    C([Charm]) --> A[Application]
    A -->|Instances of| U[Unit]
    U -->|Running on| M[Machine]
    M -->|Metadata| M_I(IP)
    M -->|Metadata| M_H(Hostname)

All filters are evaluated by traversing these relationships.

Only these object types can be queried as the top-level OBJECT:

When filtering units or machines, you can reference these Juju objects:

jockey <OBJECT> [FILTER ...] [OPTIONS]

• <OBJECT>: A queryable object type (u or m) or alias
• [FILTER ...]: Zero or more filter expressions
• [OPTIONS]: --file <path> to query a Juju status JSON file

<ATTRIBUTE><OPERATOR><VALUE>

• <ATTRIBUTE>: A filterable attribute (e.g., app, host, charm)
• <OPERATOR>: One of =, ^=, ~, ^~
• <VALUE>: The string to match

jockey u

jockey m

jockey u app=etcd

Returns all units of the etcd application.

jockey u charm=nrpe

Returns all units running the nrpe charm.

jockey m host~node

Returns machines whose hostname contains "node".

jockey u machine=0

Returns units running on machine 0 (and its containers).

jockey u app=nova machine^=0

Returns units of the nova application that are NOT on machine 0.

jockey m m^~lxd

Returns all non-LXD machines (physical machines only).

jockey u --file /tmp/status.json app=mysql

Returns mysql units from a local status file.

• --file /path/to/status.json queries a local Juju status JSON file.
• Without --file, Jockey queries Juju CLI output and uses a local cache.
• The in-memory status used for filtering is intentionally narrowed to fields needed by the currently supported query/filter paths.