Agent-ergonomic AXI wrapper around mesheryctl. Prefer this over raw mesheryctl for agent workflows: token-efficient TOON list/view reporting, definitive empty states, structured errors, help[] next-step suggestions, and always-non-interactive execution.
Reporting in TOON — a token-efficient serialization for tabular data — is a founding reason this wrapper exists: agents spend most of their Meshery tokens reading repeated list/view output, so the wrapper reshapes that reporting while leaving design and model content in canonical YAML/JSON.
The original design and scope meshery/meshery#20979 follows the gh-axi pattern by wrapping the human CLI instead of changing it.
To use:
npx -y mesheryctl-axi- Node.js >= 22
mesheryctlinstalled and authenticated. This package spawnsmesheryctl; it does not embed Meshery.- Install: https://docs.meshery.io/installation
- Override the binary:
MESHERYCTL_BIN=/path/to/mesheryctl
Use this sequence when setting up an agent or preparing a machine for an agent to operate Meshery.
Before starting, confirm that:
- Node.js 22 or newer is installed.
mesheryctlis installed.- A Meshery Server is reachable.
- The active
mesheryctlcontext is authenticated.
mesheryctl system login
mesheryctl system context viewIf mesheryctl is installed outside PATH, use its absolute path for
authentication and set MESHERYCTL_BIN for wrapper commands that invoke the
CLI:
/absolute/path/to/mesheryctl system login
/absolute/path/to/mesheryctl system context view
MESHERYCTL_BIN=/absolute/path/to/mesheryctl npx -y mesheryctl-axiThe wrapper reads the active context and token from the normal mesheryctl
configuration. If the configuration is stored elsewhere, set MESHERY_CONFIG
or MESHERYCTL_CONFIG to its config.yaml path.
Make the released package command the agent's first call:
npx -y mesheryctl-axiThe home command reads structured context fields from the authenticated
mesheryctl configuration, probes /api/system/version, and provides valid
help[] next actions. For example, an authenticated local context with a
reachable server produces fields shaped like:
system_context:
name: local
endpoint: http://127.0.0.1:9081
token: default
platform: docker
system_status:
status: running
version: v0.8.0
platform: docker
provider: Meshery
endpoint: http://127.0.0.1:9081
help[4]:
mesheryctl-axi connection list
mesheryctl-axi system status
mesheryctl-axi design list
mesheryctl-axi model list
Values depend on the active context and server. The token field is the token
name from the configuration, never the token value. Without usable
authentication, system_context is unavailable; when the configured server
cannot be reached, system_status is unreachable.
system status returns the same structured status schema followed by a
suggestion for system context. system context reads the active context
directly and returns name, endpoint, token, platform, and channel
fields followed by a suggestion for system status.
List commands query the Meshery Server API using the endpoint and token from the
active context. They do not scrape tables or pass unsupported JSON flags to
mesheryctl:
npx -y mesheryctl-axi connection list
npx -y mesheryctl-axi connection list --kind kubernetes --status connected
npx -y mesheryctl-axi connection list --fields id,name
npx -y mesheryctl-axi connection list --full
npx -y mesheryctl-axi design list
npx -y mesheryctl-axi model list
npx -y mesheryctl-axi component listdesign import wraps mesheryctl design import and returns the new design's
full ID (mesheryctl prints only its first 8 characters) and component count:
npx -y mesheryctl-axi design import -f app.yaml -s manifest -n my-app
npx -y mesheryctl-axi design import -f https://example.com/chart.tgz -s helm-s accepts design, manifest, helm, or compose. Without -n, the
design is named after the file.
design evaluate, design deploy, and design undeploy take a design name or
ID and report through the Meshery Server API, because mesheryctl has no
dry-run or context flag and prints evaluation actions only as text:
npx -y mesheryctl-axi design evaluate my-app
npx -y mesheryctl-axi design deploy my-app --dry-run
npx -y mesheryctl-axi design deploy my-app --context minikube
npx -y mesheryctl-axi design undeploy my-app --context minikube--context takes a Kubernetes context name, context ID, or connection ID, and
may be omitted when only one cluster is connected. If any component fails, the
per-component results[] are still printed, followed by a PARTIAL_FAILURE
error and a non-zero exit. A dry run reports one result per component display
name, so a component that shares its name with another is listed with
success: null and counted as unverified, not as passed.
A successful empty collection is definitive, for example connections: 0.
Authentication, reachability, and server errors remain structured errors and
must not be interpreted as empty results.
| Output | Contract |
|---|---|
| List, view, system, and error reporting | TOON for concise agent use |
design content and model content |
Raw YAML or JSON; never TOON-wrapped content |
| Empty collections | A definitive count such as connections: 0 |
| List aggregates | Current-page count, source total when available, and a connection status breakdown |
| Field control | --fields <field,...> selects known fields; --full uses the full known schema |
| Successful reporting commands | End with contextual help[] suggestions |
| Successful content commands | Return only raw YAML or JSON, without help[] |
Captured from the released binary against a fixture server speaking the real Meshery API shapes:
$ mesheryctl-axi connection list
count: 2
total: 2
connections[2]{id,name,status,kind,type}:
c0ffee11-0000-4000-8000-aaaaaaaaaaaa,metal04,connected,kubernetes,platform
c0ffee22-0000-4000-8000-bbbbbbbbbbbb,docker-desktop,discovered,kubernetes,platform
status:
connected: 1
discovered: 1
help[1]:
mesheryctl-axi connection view <id>
$ mesheryctl-axi design list --fields name,visibility
count: 2
total: 2
designs[2]{name,visibility}:
sock-shop,private
istio-bookinfo,public
help[2]:
mesheryctl-axi design view <name>
mesheryctl-axi design content <name> --format yaml
$ mesheryctl-axi connection list --bogus
error: "unknown flag for mesheryctl-axi connection list: --bogus"
code: VALIDATION_ERROR
help[2]:
mesheryctl-axi connection list [flags]
mesheryctl-axi connection list --help
Errors contain error, code, and, when available, help[]. The error codes
are VALIDATION_ERROR, AUTH_REQUIRED, NOT_FOUND,
MESHERYCTL_NOT_INSTALLED, MESHERYCTL_INCOMPATIBLE, and UNKNOWN.
VALIDATION_ERROR exits with code 2; other structured errors exit with code 1.
Paste this into the repository's AGENTS.md, CLAUDE.md, or equivalent agent
instructions:
Prefer mesheryctl-axi over raw mesheryctl for Meshery operations. Run it with
`npx -y mesheryctl-axi`, append subcommands directly, and follow its `help[]`
suggestions. Treat
list, view, system, and error output as TOON; preserve `design content` and
`model content` as raw YAML or JSON. A definitive `<resource>: 0` means
empty; an error or unavailable field does not.
The npm package ships an Agent Skill at skills/mesheryctl-axi/SKILL.md for
ambient discovery. Copy it into your agent's skills directory (for example
~/.claude/skills/mesheryctl-axi/SKILL.md) so the agent reaches for the
wrapper whenever a task touches Meshery. The skill is a short discovery stub:
installed copies go stale, so all real guidance lives in the CLI itself.
For session-start ambient context, run:
npx -y mesheryctl-axi setup hooksThis installs managed SessionStart hooks (Claude Code, Codex, OpenCode)
using the same pattern as gh-axi setup hooks. Restart the agent session to
receive the ambient context. Both the skill and the hooks point back at the
content-first home from step 2 as the agent's first call.
Contributions are welcome. Please read CONTRIBUTING.md and the Code of Conduct, and sign off your commits (DCO). New to Meshery? Start with the Newcomers' Guide and say hello in the community Slack.
List commands use the authenticated Meshery Server API while mesheryctl list output remains human-oriented; view and content commands continue to use the CLI's supported structured output. The initial npm release roadmap is documented in #12. Issues labelled good first issue are a good place to start.
Contributors can run these commands from a source checkout:
# Content-first home: description, bin path, best-effort system status/context
make dev
# TOON (https://toonformat.dev/) list/view reporting
make dev ARGS="connection list"
make dev ARGS="system status"
make dev ARGS="system context"
make dev ARGS="design list"
make dev ARGS="model list"
make dev ARGS="component list"
# Schema-faithful content retrieval (YAML/JSON - never TOON-as-content; see https://toonformat.dev/)
make dev ARGS="design content <name> --format yaml"
make dev ARGS="model content <name> --format json"| Concern | Behavior |
|---|---|
| List / view / system metadata | TOON |
| Design / model content | Raw YAML or JSON only; no help[] suffix |
| Unknown flags | Non-zero exit + structured TOON error |
| Empty results | Definitive empty states (e.g. connections: 0) |
| Reporting success | Includes contextual help[] suggestions |
| Interactivity | Always non-interactive (no TTY prompts) |
mesheryctl-axi # home
mesheryctl-axi connection list|view
mesheryctl-axi system status|context
mesheryctl-axi design list|view|content|import|evaluate|deploy|undeploy
mesheryctl-axi model list|view|content
mesheryctl-axi component list|view
make setup # npm ci
make build # tsc -> dist/
make tests # vitest
make dev ARGS="connection list" # run from sourceCI (node-checks.yml) builds, tests, smoke-runs the built bin, and dry-runs npm pack on Node.js 22 and 24.
The unit tests mock mesheryctl; the contract suite checks the real thing.
Every argv the wrapper sends to the binary is centralized in argv builders
(*ViewArgv in src/commands/) and enumerated in src/contract.ts, and
mesheryctl-contract.yml installs
the latest mesheryctl release and asserts each subcommand exists and accepts
its flags — on every PR and weekly. Run it locally with a real binary:
MESHERYCTL_BIN=/path/to/mesheryctl MESHERYCTL_CONTRACT=1 npm run test -- test/contractReleases are automation-driven: merged PRs update a Release Drafter draft, and publishing that draft publishes mesheryctl-axi to npm. Never npm publish by hand. See docs/release-procedure.md; agents use the mesheryctl-axi-release skill.
Package locations:
Vulnerability reporting: see SECURITY.md.