\n\n# mesheryctl-axi\n\nAgent-ergonomic [AXI](https://axi.md/) wrapper around [`mesheryctl`](https://docs.meshery.io/reference/mesheryctl). Prefer this over raw `mesheryctl` for agent workflows: token-efficient [**TOON**](https://toonformat.dev/) list/view reporting, definitive empty states, structured errors, `help[]` next-step suggestions, and always-non-interactive execution.\n\nReporting in [TOON](https://toonformat.dev/) — 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.\n\n\n_The original design and scope [meshery/meshery#20979](https://github.com/meshery/meshery/issues/20979) follows the [`gh-axi`](https://github.com/kunchenguid/gh-axi) pattern by wrapping the human CLI instead of changing it._\n\n## How to Use\n\nTo use:\n\n```bash\nnpx -y mesheryctl-axi\n```\n\n### Prerequisites\n\n- **Node.js >= 22**\n- **`mesheryctl` installed and authenticated.** This package spawns `mesheryctl`; it does not embed Meshery.\n - Install: https://docs.meshery.io/installation\n - Override the binary: `MESHERYCTL_BIN=/path/to/mesheryctl`\n\n### Agent quickstart\n\nUse this sequence when setting up an agent or preparing a machine for an agent to operate Meshery.\n\n#### 1. Prepare the environment\n\nBefore starting, confirm that:\n\n- Node.js 22 or newer is installed.\n- `mesheryctl` is installed.\n- A Meshery Server is reachable.\n- The active `mesheryctl` context is authenticated.\n\n```bash\nmesheryctl system login\nmesheryctl system context view\n```\n\nIf `mesheryctl` is installed outside `PATH`, use its absolute path for\nauthentication and set `MESHERYCTL_BIN` for wrapper commands that invoke the\nCLI:\n\n```bash\n/absolute/path/to/mesheryctl system login\n/absolute/path/to/mesheryctl system context view\nMESHERYCTL_BIN=/absolute/path/to/mesheryctl make dev\n```\n\nThe wrapper reads the active context and token from the normal `mesheryctl`\nconfiguration. If the configuration is stored elsewhere, set `MESHERY_CONFIG`\nor `MESHERYCTL_CONFIG` to its `config.yaml` path.\n\n#### 2. Start with the content-first home\n\nDuring pre-release development, make the no-argument source command the\nagent's first call:\n\n```bash\nmake dev\n```\n\nThe home command reads structured context fields from the authenticated\n`mesheryctl` configuration, probes `/api/system/version`, and provides valid\n`help[]` next actions. For example, an authenticated local context with a\nreachable server produces fields shaped like:\n\n```text\nsystem_context:\n name: local\n endpoint: http://127.0.0.1:9081\n token: default\n platform: docker\nsystem_status:\n status: running\n version: v0.8.0\n platform: docker\n provider: Meshery\n endpoint: http://127.0.0.1:9081\nhelp[4]:\n mesheryctl-axi connection list\n mesheryctl-axi system status\n mesheryctl-axi design list\n mesheryctl-axi model list\n```\n\nValues depend on the active context and server. The `token` field is the token\nname from the configuration, never the token value. Without usable\nauthentication, `system_context` is `unavailable`; when the configured server\ncannot be reached, `system_status` is `unreachable`.\n\n`system status` returns the same structured status schema followed by a\nsuggestion for `system context`. `system context` reads the active context\ndirectly and returns `name`, `endpoint`, `token`, `platform`, and `channel`\nfields followed by a suggestion for `system status`.\n\n#### 3. Use reporting and content commands correctly\n\nList commands query the Meshery Server API using the endpoint and token from the\nactive context. They do not scrape tables or pass unsupported JSON flags to\n`mesheryctl`:\n\n```bash\nmake dev ARGS=\"connection list\"\nmake dev ARGS=\"connection list --kind kubernetes --status connected\"\nmake dev ARGS=\"connection list --fields id,name\"\nmake dev ARGS=\"connection list --full\"\nmake dev ARGS=\"design list\"\nmake dev ARGS=\"model list\"\nmake dev ARGS=\"component list\"\n```\n\nA successful empty collection is definitive, for example `connections: 0`.\nAuthentication, reachability, and server errors remain structured errors and\nmust not be interpreted as empty results.\n\n| Output | Contract |\n| --- | --- |\n| List, view, system, and error reporting | [TOON](https://toonformat.dev/) for concise agent use |\n| `design content` and `model content` | Raw YAML or JSON; never [TOON](https://toonformat.dev/)-wrapped content |\n| Empty collections | A definitive count such as `connections: 0` |\n| List aggregates | Current-page `count`, source `total` when available, and a connection status breakdown |\n| Field control | `--fields ` selects known fields; `--full` uses the full known schema |\n| Successful reporting commands | End with contextual `help[]` suggestions |\n| Successful content commands | Return only raw YAML or JSON, without `help[]` |\n\n#### Example session\n\nCaptured from the released binary against a fixture server speaking the real\nMeshery API shapes:\n\n```text\n$ mesheryctl-axi connection list\ncount: 2\ntotal: 2\nconnections[2]{id,name,status,kind,type}:\n c0ffee11-0000-4000-8000-aaaaaaaaaaaa,metal04,connected,kubernetes,platform\n c0ffee22-0000-4000-8000-bbbbbbbbbbbb,docker-desktop,discovered,kubernetes,platform\nstatus:\n connected: 1\n discovered: 1\nhelp[1]:\n mesheryctl-axi connection view \n```\n\n```text\n$ mesheryctl-axi design list --fields name,visibility\ncount: 2\ntotal: 2\ndesigns[2]{name,visibility}:\n sock-shop,private\n istio-bookinfo,public\nhelp[2]:\n mesheryctl-axi design view \n mesheryctl-axi design content --format yaml\n```\n\n```text\n$ mesheryctl-axi connection list --bogus\nerror: \"unknown flag for mesheryctl-axi connection list: --bogus\"\ncode: VALIDATION_ERROR\nhelp[2]:\n mesheryctl-axi connection list [flags]\n mesheryctl-axi connection list --help\n```\n\nErrors contain `error`, `code`, and, when available, `help[]`. The error codes\nare `VALIDATION_ERROR`, `AUTH_REQUIRED`, `NOT_FOUND`,\n`MESHERYCTL_NOT_INSTALLED`, `MESHERYCTL_INCOMPATIBLE`, and `UNKNOWN`.\n`VALIDATION_ERROR` exits with code 2; other structured errors exit with code 1.\n\n#### 4. Add the agent instruction\n\nPaste this into the repository's `AGENTS.md`, `CLAUDE.md`, or equivalent agent\ninstructions:\n\n```text\nPrefer mesheryctl-axi over raw mesheryctl for Meshery operations. During\npre-release development, run it from the source checkout with `make dev` and\npass subcommands through `ARGS`, then follow its `help[]` suggestions. Treat\nlist, view, system, and error output as TOON; preserve `design content` and\n`model content` as raw YAML or JSON. A definitive `: 0` means\nempty; an error or unavailable field does not.\n```\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md), and sign off your commits ([DCO](https://docs.meshery.io/project/contributing#signing-off-on-commits-developer-certificate-of-origin)). New to Meshery? Start with the [Newcomers' Guide](https://layer5.io/community/newcomers) and say hello in the [community Slack](https://slack.meshery.io).\n\nList 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. [#12](https://github.com/meshery-extensions/mesheryctl-axi/issues/12) tracks everything left before the first npm release. Issues labelled [`good first issue`](https://github.com/meshery-extensions/mesheryctl-axi/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22) are a good place to start.\n\nRun these commands from the source checkout during pre-release development:\n\n```bash\n# Content-first home: description, bin path, best-effort system status/context\nmake dev\n\n# TOON (https://toonformat.dev/) list/view reporting\nmake dev ARGS=\"connection list\"\nmake dev ARGS=\"system status\"\nmake dev ARGS=\"system context\"\nmake dev ARGS=\"design list\"\nmake dev ARGS=\"model list\"\nmake dev ARGS=\"component list\"\n\n# Schema-faithful content retrieval (YAML/JSON - never TOON-as-content; see https://toonformat.dev/)\nmake dev ARGS=\"design content --format yaml\"\nmake dev ARGS=\"model content --format json\"\n```\n\n### Design notes\n\n| Concern | Behavior |\n| --- | --- |\n| List / view / system metadata | [TOON](https://toonformat.dev/) |\n| Design / model **content** | Raw YAML or JSON only; no `help[]` suffix |\n| Unknown flags | Non-zero exit + structured [TOON](https://toonformat.dev/) error |\n| Empty results | Definitive empty states (e.g. `connections: 0`) |\n| Reporting success | Includes contextual `help[]` suggestions |\n| Interactivity | Always non-interactive (no TTY prompts) |\n\n### Commands (v1)\n\n```\nmesheryctl-axi # home\nmesheryctl-axi connection list|view\nmesheryctl-axi system status|context\nmesheryctl-axi design list|view|content\nmesheryctl-axi model list|view|content\nmesheryctl-axi component list|view\n```\n\n### Development\n\n```bash\nmake setup # npm ci\nmake build # tsc -> dist/\nmake tests # vitest\nmake dev ARGS=\"connection list\" # run from source\n```\n\nCI ([`node-checks.yml`](.github/workflows/node-checks.yml)) builds, tests, smoke-runs the built bin, and dry-runs `npm pack` on Node.js 22 and 24.\n\nThe unit tests mock `mesheryctl`; the contract suite checks the real thing.\nEvery argv the wrapper sends to the binary is centralized in argv builders\n(`*ViewArgv` in `src/commands/`) and enumerated in `src/contract.ts`, and\n[`mesheryctl-contract.yml`](.github/workflows/mesheryctl-contract.yml) installs\nthe latest `mesheryctl` release and asserts each subcommand exists and accepts\nits flags — on every PR and weekly. Run it locally with a real binary:\n\n```bash\nMESHERYCTL_BIN=/path/to/mesheryctl MESHERYCTL_CONTRACT=1 npm run test -- test/contract\n```\n\n### Releasing\n\nReleases 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`](docs/release-procedure.md); agents use the [`mesheryctl-axi-release`](.agents/skills/mesheryctl-axi-release/SKILL.md) skill.\n\nPackage locations:\n\n- [npm package page](https://www.npmjs.com/package/mesheryctl-axi)\n- [npm registry metadata](https://registry.npmjs.org/mesheryctl-axi)\n\n### Security\n\nVulnerability reporting: see [SECURITY.md](SECURITY.md).\n\n## License\n\n[Apache-2.0](LICENSE)\n","readmeFilename":"README.md"}
![](\"https://raw.githubusercontent.com/meshery/meshery/master/.github/assets/images/readme/meshery-logo-dark-text-side.svg\"\nalt=\"Meshery){kind=logo}
![](\"https://img.shields.io/npm/v/mesheryctl-axi?color=informational\")
![](\"https://img.shields.io/github/actions/workflow/status/meshery-extensions/mesheryctl-axi/node-checks.yml?branch=master&label=node%20checks\")
![](\"https://img.shields.io/github/issues/meshery-extensions/mesheryctl-axi/help%20wanted?color=informational\")
![](\"https://img.shields.io/github/license/meshery-extensions/mesheryctl-axi?color=brightgreen\")
![](\"https://img.shields.io/badge/Slack-@meshery.svg?logo=slack\"){kind=icon}