Skip to main content
The Yertle CLI is an open-source Python command-line client for exploring and scripting Yertle workspaces. Repo: model-context/yertle-python · Package: yertle on PyPI

​
Installation

The CLI ships in the yertle package on PyPI. Install it as a tool with uv:
pipx install yertle works the same way. Verify:
A tool install gives you the command, not the library. uv tool puts the package in an isolated environment and links only the entry points onto your PATH, so import yertle in a script will not find it. To use the Python SDK, install into the project that imports it — uv add yertle — which gives you both import yertle and the CLI via uv run yertle.
Python entry points are not conditional on extras, so the install also puts a yertle-sre command on your PATH. It belongs to an optional agent that is not documented yet; running it just tells you which extra it would need. Ignore it.
To upgrade later:
That works as long as you installed without pinning a version. Pinning (uv tool install "yertle==0.3.0") records the exact version as the requirement, so later upgrades have nothing to move to — reinstall with uv tool install --force yertle to unpin.

​
Getting started

yertle login defaults to production. Pass --api-url to point at a different backend and persist that choice, or set $YERTLE_API_URL for a single command.

​
Commands

Commands are noun-then-verb, like gh and the AWS CLI. A bare noun prints its subcommands rather than running a default action.

​
Organizations

​
Nodes

nodes search is the fastest way from a description to a node. Add --expand standard to pull in the surrounding nodes and connections in the same call:
It also takes --top-k, --tag key=value (repeatable), --scope-root, --dir-prefix, and --include-text.

​
Authentication and diagnostics

yertle auth status is the first thing to run when something behaves unexpectedly. It reports what is in effect alongside the source each value was resolved from, without making a request:
It exits non-zero when no token resolves, so it works as a precondition check in scripts.

​
Choosing an organization

Most commands act on one organization, resolved in this order:
Commands that can span organizations — nodes list and nodes tree — do so by default. Commands that cannot address more than one — nodes show and nodes search — ask you to pick one.

​
Output formats

Every data command takes --format table (default) or --format json. Errors go to stderr and exit non-zero, so piping is safe:

​
Configuration

Credentials resolve per key, so the two settings can come from different places:
Environment variables take precedence over the config file, which makes them the right way to point at a different backend for a single command without disturbing saved credentials. yertle login writes the config file with owner-only permissions (0600) and merges into any existing contents rather than replacing them.
Upgrading from 0.2.0 or earlier: yertle orgs is now yertle orgs list. Every command is noun-then-verb, so a bare yertle orgs prints its subcommands instead of listing. yertle login no longer requires --api-url; it defaults to production.

​
Contributing

The CLI is open source and welcomes contributions — see model-context/yertle-python. The API reference on this docs site is the source of truth for endpoint signatures and request/response shapes — use it when adding new commands.