Agenetix CLI

agenetix is the command-line interface for Agenetix organizations, MCP servers, gateways, agents, members, invitations, and service-account API keys.

Install

npm i -g @agenetix/cli

Install with npm install -g @agenetix/cli.

For local development:

npm install
npm run build
node dist/index.js --help

Publishing

publish-npm.yml is the only npm publish entry point. Merging to main does not publish latest.

• Pull request against main — publishes a preview dist-tag, for example @agenetix/cli@pr-12. The workflow comments with the exact package ref.
• v* tag (for example v2.0.3) — publishes latest. Bump package.json first; npm will not overwrite an already-published version.

To test a CLI change inside a platform PR preview, add the ref to infra/preview-packages.json in that PR:

{
  "@agenetix/cli": "@agenetix/cli@pr-12"
}

The platform preview deploy installs that package before image builds, runs a CLI smoke check, and includes the resolved npm package link in the platform PR preview comment.

Human Login

Human operators use OAuth device authorization. The API must expose /api/v1/cli/config and the device_authorization_endpoint.

By default the CLI targets production (https://api.agenetix.com) and opens your browser for device login. Use --no-browser to print the URL only.

agenetix auth login
agenetix auth status
agenetix auth whoami
agenetix servers list

The CLI uses your primary organization automatically (the first organization returned by the API), matching the SaaS dashboard. You do not need to select an organization manually.

Local AppHost:

agenetix auth login --api-url http://localhost:5150

Service-Account Login

Automation and CI should use an Agenetix service-account API key. You can either store one active service-account login locally or pass the key through environment variables.

agenetix auth service-account login \
  --api-url https://api.agenetix.com \
  --key agenetix_sk_...

agenetix servers list

Equivalent environment-only usage:

AGENETIX_API_URL=https://api.agenetix.com \
AGENETIX_API_KEY=agenetix_sk_... \
agenetix servers list

Use --org <organization-id> only when you need to override the default organization for a single command.

Common Workflows

agenetix members invite [email protected] --role developer
agenetix members invitations list

agenetix api-keys create --name deploy-bot --role developer
agenetix api-keys list

agenetix servers create --openapi-file ./openapi.yaml
agenetix servers get <server-id>
agenetix servers update <server-id> --name "Production API"
agenetix servers update <server-id> --openapi-file ./openapi.yaml
agenetix logs stream <server-id>
agenetix operations list <server-id> --json
agenetix servers checks <server-id>
agenetix smoke tools-list <server-id>
agenetix servers delete <server-id> --yes

agenetix servers custom-domain validate <server-id> --hostname mcp.example.com --json
agenetix servers custom-domain get <server-id> --json

agenetix agents list
agenetix agents budget defaults <agent-id> --monthly-usd 10000 --default-user-usd 5 --json
agenetix agents budget set <agent-id> --user customer_abc --monthly-usd 5 --json
agenetix agents budget get <agent-id> --user customer_abc --json
agenetix agents budget delete <agent-id> --user customer_abc --yes
agenetix agents chat <agent-id> --message "Summarize production health"

Creating or updating a hosted server starts the managed edge publish automatically. The CLI intentionally does not expose separate deploy, undeploy, region mutation, reconcile, or rollback commands to customers; those are internal platform operations.

When creating or updating from --openapi-file, the CLI reads the local JSON/YAML file, sends the spec contents to Agenetix, and records the source as an upload. The file does not need to be publicly reachable. Use servers update --openapi-file whenever the local spec changes.

Hosted Custom Domains

Hosted servers can expose one customer-owned subdomain such as mcp.example.com. Agenetix keeps the canonical platform MCP URL as a fallback and only prefers the custom URL after DNS, Azure Front Door managed TLS, and routing are active.

agenetix servers custom-domain validate <server-id> --hostname mcp.example.com --json
agenetix servers custom-domain confirm-ownership <server-id> --json
agenetix servers custom-domain get <server-id> --json
agenetix servers custom-domain finalize <server-id> --json
agenetix smoke tools-list <server-id>

The validate response returns the ownership TXT record to create at your DNS provider. After it resolves, run confirm-ownership; Agenetix then prepares the routing CNAME and Azure validation TXT records. Add those records, then run finalize to activate routing and managed TLS. delete --yes removes the custom domain from the server.

Configuration

Global flags:

--api-url, --org (advanced override), --json, --output table|json|yaml,
--yes, --wait, --timeout, --verbose, --debug-http

Environment overrides:

AGENETIX_API_URL
AGENETIX_ORG_ID
AGENETIX_ACCESS_TOKEN
AGENETIX_API_KEY
AGENETIX_DISABLE_KEYCHAIN
AGENETIX_OUTPUT
NO_COLOR

The active login and selected organization are stored at ~/.config/agenetix/config.json. Secrets use the OS keychain when keytar is available, with a 0600 local fallback. Set AGENETIX_DISABLE_KEYCHAIN=1 for CI or isolated E2E runs that should not touch the desktop keychain.