@starascendin/kortex-agent-cli

Simple CLI for Kortex's direct JSON Agent API.

This package is intended for agent runtimes such as OpenClaw that should talk to Kortex over the direct /agent-api surface instead of MCP.

What it does

• discovers available Kortex operations
• fetches API metadata
• invokes a single operation with JSON input
• prints JSON to stdout for easy agent consumption

Requirements

Provide:

• KORTEX_AGENT_URL or KORTEX_API_URL
• KORTEX_API_KEY

The URL can be either:

• the Convex site root, for example https://your-deployment.convex.site
• the full API path, for example https://your-deployment.convex.site/agent-api

The CLI normalizes the URL automatically.

Local usage

From the repo root:

pnpm --filter @starascendin/kortex-agent-cli build
node packages/agent-cli/dist/index.js info --url https://your-deployment.convex.site --api-key krtx_xxx
node packages/agent-cli/dist/index.js operations --url https://your-deployment.convex.site --api-key krtx_xxx
node packages/agent-cli/dist/index.js call list_companies --url https://your-deployment.convex.site --api-key krtx_xxx --input '{"limit":10}'

Build the package:

pnpm --filter @starascendin/kortex-agent-cli build

Then run the built binary:

node packages/agent-cli/dist/index.js info --url https://your-deployment.convex.site --api-key krtx_xxx
node packages/agent-cli/dist/index.js operations --url https://your-deployment.convex.site --api-key krtx_xxx
node packages/agent-cli/dist/index.js call list_companies --url https://your-deployment.convex.site --api-key krtx_xxx --input '{"limit":10}'

Commands

info

Returns API metadata and the operations available to the supplied key.

kortex-agent info --url <URL> --api-key <KEY>

operations

Returns the operation list and input schemas available to the supplied key.

kortex-agent operations --url <URL> --api-key <KEY>

call

Invokes one Kortex operation.

kortex-agent call <operation> --url <URL> --api-key <KEY> [--input <JSON|@file|->]

Input modes:

• inline JSON: --input '{"limit":10}'
• file: --input @payload.json
• stdin: --input -

Optional flags:

• --compact for compact JSON output

Examples

Inline JSON:

node packages/agent-cli/dist/index.js call search_companies --url https://your-deployment.convex.site --api-key krtx_xxx --input '{"query":"openai","limit":5}'

From a file:

node packages/agent-cli/dist/index.js call update_company --url https://your-deployment.convex.site --api-key krtx_xxx --input @payload.json

From stdin:

cat payload.json | node packages/agent-cli/dist/index.js call create_note --url https://your-deployment.convex.site --api-key krtx_xxx --input -

OpenClaw skill

The OpenClaw-oriented skill for this CLI lives at:

packages/agent-cli/skills/kortex-agent-api/SKILL.md

Use that skill when you want an OpenClaw agent to operate against Kortex through the direct Agent API with read-before-write discipline and scoped mutations.

Install from npm

Once published, install it with:

npm install -g @starascendin/kortex-agent-cli

Then run:

kortex-agent info --url https://your-deployment.convex.site --api-key krtx_xxx

Publishing

This package is set up to publish from GitHub Actions via npm trusted publishing.

Workflow:

• .github/workflows/publish-agent-cli.yml

Publish paths:

• manually via GitHub Actions workflow_dispatch
• automatically on tags matching agent-cli-v*

Before the workflow can publish successfully, configure trusted publishing in npm for:

• package: @starascendin/kortex-agent-cli
• repository: this GitHub repo
• workflow: publish-agent-cli.yml
• branch or environment: typically main

Release flow:

1. Bump packages/agent-cli/package.json version.
2. Merge to main.
3. Either run the workflow manually, or push a tag like agent-cli-v0.1.0.