@agentcentral/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Verhoeven
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# agentcentral CLI
+
+Command-line access to the agentcentral hosted MCP server. List and call the key-scoped tool surface,
+run a transparent stdio bridge for local MCP clients, and diagnose connectivity — all over the same
+stateless Streamable HTTP transport an MCP client uses.
+
+## Install (from the monorepo)
+
+```bash
+pnpm install
+pnpm --filter @agent-central/cli build
+# run the built bin
+node packages/cli/dist/index.js --help
+```
+
+Once published the `agentcentral` bin is on `PATH`; the examples below use that name.
+
+## Authentication
+
+The CLI resolves an `ac_live_...` API key with this precedence (highest first):
+
+1. `--api-key-stdin` (key piped on stdin — never an argv value)
+2. `--profile <name>` (a stored profile)
+3. `AGENT_CENTRAL_API_KEY` environment variable
+4. `AGENTCENTRAL_API_KEY` (deprecated alias; warns once)
+5. the active profile, then a lone stored profile
+
+The fastest path is the environment variable:
+
+```bash
+export AGENT_CENTRAL_API_KEY=ac_live_xxxxxxxxxxxx
+agentcentral account info
+```
+
+Keys are single-marketplace bound and are only ever echoed redacted (`ac_live_***1234`).
+
+### Stored profiles
+
+```bash
+agentcentral auth login           # prompt + store under the "default" profile
+agentcentral profiles add ca      # store a named profile (key read from stdin)
+agentcentral profiles use ca      # set the active profile
+agentcentral profiles list        # show stored profiles (keys redacted)
+agentcentral auth status          # show the currently-resolved key + endpoint
+```
+
+The config lives at `${XDG_CONFIG_HOME:-~/.config}/agentcentral/config.json`, written `0600`.
+
+## Common commands
+
+### Inspect and call tools
+
+```bash
+agentcentral tools list                         # key-scoped tools (json)
+agentcentral tools list --format table          # aligned table
+agentcentral tools describe get_orders          # full descriptor
+agentcentral tools schema get_orders            # raw JSON Schema
+
+# Call a read tool with inline JSON, an @file, or "-" (stdin):
+agentcentral tools call get_orders '{"limit":5}'
+agentcentral tools call get_orders @args.json
+echo '{"limit":5}' | agentcentral tools call get_orders -
+```
+
+Write tools default to a non-mutating **preview**. To submit, pass `--yes` and an `--idempotency-key`:
+
+```bash
+agentcentral tools call update_keyword_bids @bids.json \
+  --yes --idempotency-key "$(uuidgen)"
+```
+
+### Run the stdio MCP bridge
+
+`mcp serve` relays newline-delimited JSON-RPC between a local MCP client and the hosted server. stdout
+carries JSON-RPC only — every diagnostic goes to stderr.
+
+```bash
+agentcentral mcp serve                       # transparent bridge
+agentcentral mcp serve --read-only           # advisory: hide write tools from tools/list
+agentcentral mcp serve --domain ads,inventory
+
+agentcentral mcp config claude               # print client config (Claude/Cursor/OpenClaw/Hermes)
+agentcentral mcp test                        # check hosted-server reachability
+```
+
+### Diagnose
+
+```bash
+agentcentral doctor                # CLI/runtime versions, auth (redacted), /health, account resolution
+agentcentral doctor --format markdown
+```
+
+## Global flags
+
+Every command accepts: `--format/-f json|ndjson|table`, `--output/-o <path>`, `--profile/-p <name>`,
+`--timeout <ms>`, `--limit <n>`, `--quiet/-q`, `--no-color`, `--verbose`, `--request-id <id>`,
+`--yes/-y`, `--idempotency-key <key>`, `--api-key-stdin`.
+
+## Exit codes
+
+| Code | Name | Meaning |
+|------|------|---------|
+| 0 | Success | command completed |
+| 1 | GeneralFailure | unclassified error |
+| 2 | UsageError | bad flags / non-tabular result requested as `--format table` |
+| 3 | AuthError | HTTP 401, invalid connector token, or missing API key |
+| 4 | PermissionDenied | key-scope denial or tenant lifecycle status |
+| 5 | ValidationFailed | input/tool validation (`-32602`, write `validation_error`) |
+| 6 | TransportFailure | network failure or 429 after retries exhausted |
+| 7 | ToolExecutionFailed | tool executed but errored |
+| 8 | Timeout | request timed out |
+| 9 | PartialWrite | a write partially succeeded |