@ekzs/cli

Version: 0.5.0

Ekz is a local coding agent for e-Kwanza Pagamento Integrado v2.4 — like Claude Code, but specialized for GPO, EMIS ref, Ticket, payment architecture, and webhook-safe integrations across Node/Next.js, ASP.NET Core/.NET, Spring Boot, and Laravel backends.

Runs in your repo. Edits files directly in agent or plan mode. You bring your own LLM key (BYOK) — Cursor, OpenAI, Anthropic, DeepSeek, and more.

Install

npm install -g @ekzs/cli
ekz setup

Clean install (~15 packages). Keys are configured locally via ekz setup or ekz providers — never committed to git.

Cursor: if you pick Cursor during ekz setup, Ekz checks for @cursor/sdk before asking for your API key and offers to run npm install -g @cursor/sdk for you. You can also install it yourself beforehand:

npm install -g @ekzs/cli @cursor/sdk

Other providers (OpenAI, Anthropic, etc.) need no extra packages.

Supported backend stacks

Ekz can inspect and edit any text-based backend through the agent tools. The scanner and skills are first-class for:

• Node/Next.js/TypeScript apps using @ekzs/connect or a local provider adapter
• ASP.NET Core / .NET Web API apps using native C# adapters, IOptions, IHttpClientFactory, controllers/minimal APIs, EF Core, and hosted services
• Java / Spring Boot apps using native Java adapters, configuration properties, WebClient or RestClient, JPA, and scheduled jobs
• Laravel / PHP apps using native services, config/env, HTTP client, migrations, queues, and signed webhook routes

For non-Node projects, Ekz does not try to install the TypeScript SDK. It uses the SDK only as an API reference and builds a native e-Kwanza adapter in the target app's style.

ekz doctor understands .env, .env.local, .NET Ekwanza__... environment variables, and Ekwanza sections in appsettings*.json.

First run — ekz setup

ekz setup
# aliases: ekz configurar · ekz 设置

Wizard steps:

1. Language — Português · English · 中文
2. Your name — shown on the splash screen
3. Provider or offline — configure one LLM key, or skip to doctor/scan-only mode

When you configure a provider:

• Pick from the numbered provider list
• Cursor only: Ekz checks for @cursor/sdk and offers to install it before the API key step
• Paste your API key
• Pick a model from a predefined list (Enter = default)
• Setup finishes and exits — then run ekz to start the agent

No base URL prompts — endpoints are predefined per provider.

Stored in:

| File | Contents | |------|----------| | ~/.ekz/config.json | locale, name, offline flag, setup complete | | ~/.ekz/providers.json | active provider, API keys, models (mode 600) |

Without setup or a provider, ekz shows:

Setup required · Configuração necessária · 需要设置

  pt: Corre `ekz setup` ou `ekz --offline`
  en: Run `ekz setup` or `ekz --offline`
  zh: 运行 `ekz setup` 或 `ekz --offline`

Supported providers

| Provider | Example models (May 2026) | |----------|---------------------------| | Cursor | composer-2.5-fast, composer-2.5, claude-4.6-sonnet-thinking, gpt-5.5, … | | OpenAI | gpt-5.5, gpt-5.4-mini, gpt-4.1, o3, o4-mini, … | | Anthropic | claude-sonnet-4-6, claude-opus-4-7, claude-haiku-4-5-20251001, … | | DeepSeek | deepseek-v4-flash, deepseek-v4-pro (legacy: deepseek-chat until Jul 2026) | | Kimi (Moonshot) | kimi-k2.6, kimi-k2.5, moonshot-v1-8k, … | | Groq | llama-3.3-70b-versatile, openai/gpt-oss-120b, qwen/qwen3-32b, … | | Mistral | mistral-large-latest, codestral-latest, devstral-latest, … | | Google Gemini | gemini-3.5-flash, gemini-3.1-pro-preview, gemini-2.5-pro, … | | Ollama | llama3.3, qwen3:8b, deepseek-r1:8b, … (local tags) |

Manage keys anytime:

ekz providers          # full menu — configure, switch, remove
ekz provedores         # PT
ekz 供应商              # ZH

In the REPL: /providers, /provedores, /供应商

Modes

| Mode | Aliases | Behavior | |------|---------|----------| | agent | default, agente, 代理 | Edits files and runs commands | | plan | plano, 计划 | Plans before editing | | ask | perguntar, 问答, chat | Q&A only — no file edits |

| Mode | BYOK routing | |------|----------------| | agent / plan | Cursor → @cursor/sdk; others → tool loop (read_file, write_file, run_command) | | ask | Chat API (Cursor uses lightweight Cursor agent) |

Optional one-off override: --api-key crsr_... in agent/plan mode.

Commands

| Command | Description | |---------|-------------| | ekz setup | First-run wizard — language, name, provider or offline | | ekz / ekz agent | Interactive REPL (default: agent mode) | | ekz --mode plan | Plan before editing files | | ekz --mode ask | BYOK Q&A, no file edits | | ekz --offline | Doctor/scan answers only — no LLM | | ekz agent "fix webhook" | One-shot task with file edits | | ekz fix | Full integration audit + auto-fix pass | | ekz ask "…" | BYOK Q&A only | | ekz ask -i | Interactive ask REPL | | ekz providers | Manage LLM API keys (BYOK) | | ekz agent --resume | Continue last session (.ekz/session.json) | | ekz doctor | Env + credential checks (free) | | ekz health | OAuth + rail health (free) | | ekz scan | Lint common integration mistakes (free) | | ekz webhook <url> | POST sample webhook (free) |

REPL shortcuts

Type /help in the REPL for the full list. Also:

/providers · /mode agent|plan|ask · /doctor · /scan · /lang pt|en|zh · /save · /resume

Examples

# First time
ekz setup
ekz

# Interactive — stay in your project and iterate
ekz agent

# One-shot fix
ekz fix

# With extra context
ekz fix "Ticket webhook returns 401 on x-signature"

# Plan before editing
ekz --mode plan "Add emis_ref rail to checkout"

# Ask mode (no local edits)
ekz --mode ask "What env vars am I missing for Ticket?"

# Free checks before touching the agent
ekz doctor
ekz scan
ekz webhook http://localhost:3000/api/webhooks/ekwanza

# Resume yesterday's session
ekz agent --resume

Billing

BYOK only — usage bills through your provider account (Cursor, OpenAI, Anthropic, etc.). Ekz does not resell LLM credits.

Free commands (no API key): doctor, health, scan, webhook.

Agent tuning

EKZ_AGENT_MAX_TOOL_ROUNDS=32 controls the per-turn tool budget for BYOK providers. When the budget is reached, the agent asks the model for a no-tools summary instead of throwing a raw loop error.

Run from this repo

npm run build:cli

# Option A — wrapper (no global install)
./ekz                          # Git Bash / macOS / Linux
.\ekz                          # PowerShell / cmd
npx ekz                        # any shell, from repo root

# Option B — npm script
npm run ekz
npm run ekz -- agent "fix webhook"

# Option C — global command
npm run setup:cli              # build + npm link
ekz

Windows / PowerShell

.\ekz                          # resolves to ekz.cmd
npx ekz
npm run setup:cli              # then `ekz` works globally

Shell type is detected at launch and injected into agent turns. Override with EKZ_AGENT_SHELL=powershell|bash|cmd.

In PowerShell, use curl.exe for manual HTTP tests — bare curl is an alias for Invoke-WebRequest. Prefer ekz doctor, ekz health, ekz webhook <url>.

Session file

.ekz/session.json stores agent ID for --resume. Add .ekz/ to .gitignore.

Agent skills

18 skills under packages/cli/skills/. On build, they sync to .cursor/skills/ for local Cursor use.

| Skill | Use when | |-------|----------| | ekz-connect | Orchestrator — SDK entry points | | ekz-payment-core-architecture | Primitives, state machines, idempotency | | ekz-ekwanza-provider-adapter | Auth, config, GPO, EMIS ref, Ticket API | | ekz-webhook-normalization | Callbacks, x-signature, dedupe, routing | | ekz-one-time-product-payments | Products, checkout links, fulfillment | | ekz-ticket-invite-selling | Reservations, invite/ticket issuance | | ekz-subscription-billing | Recurring payments, grace, entitlements | | ekz-overage-billing | Metered usage, overage charges | | ekz-integration-playbook | Adapting patterns into existing codebases | | ekz-sdk-cli | @ekzs/connect, ekz doctor, CLI | | ekz-data-layer-design | Store abstraction choices | | ekz-data-postgres | Supabase / Postgres | | ekz-data-mysql | MySQL | | ekz-data-sqlite | SQLite | | ekz-data-mongo | MongoDB | | ekz-dotnet-aspnet-core | ASP.NET Core / .NET backend wiring | | ekz-java-spring-boot | Java / Spring Boot backend wiring | | ekz-laravel-php | Laravel / PHP backend wiring |

npm run sync:skills --prefix packages/cli

Language

Default replies: Portuguese (Angola). Switch in the REPL with /lang pt, /lang en, /lang zh, or start with ekz --lang en.

Publish (maintainers)

npm run build:cli
npm run publish:cli

Related

• @ekzs/connect — TypeScript SDK for v2.4
• Full report — product + agent reference