CLI Reference

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

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

Prerequisites

• Node.js 20 or later — check with node --version
• npm 10 or later — ships with Node.js 20+ (check with npm --version)

Install

The recommended way to use the CLI is via npx, which downloads the latest version automatically:

npx grexal login
npx grexal init
npx grexal dev
npx grexal push
npx grexal publish
npx grexal agent price add run_completed 0.05

Alternatively, install globally:

npm install -g grexal
grexal login
grexal init

How shipping works: push vs. publish

Shipping an agent is a two-phase flow:

1. grexal push uploads your source, builds it, and stores the resulting deployment in draft state. The agent is NOT live — users can't discover or run it.
2. grexal publish promotes a successful deployment to active. The agent becomes discoverable in the marketplace and can be invoked.

Between the two, you can test your build privately from the dashboard ("Test Run" button on any succeeded deployment) or configure pricing via grexal agent price <subcommand> and visibility via grexal agent set-*.

Why two phases? Deploying an agent is irreversible from a reputational/financial standpoint. A bug or a mispriced agent can cost you real money. Splitting build from publish lets you verify before going live.

The short path: grexal deploy

If you just want "build and go live", grexal deploy is an alias for grexal push --publish:

npx grexal deploy      # build + publish in one step
npx grexal push --publish   # same thing, explicit

Use this during iteration. For anything customers will see, prefer push → test → publish.

Authentication

npx grexal login

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

Required before any command that talks to the platform (push, publish, unpublish, delete, agent, env).

$ 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. Two questions (language and name) and done.

Non-interactive mode

Pass both flags to skip all prompts — useful for scripting and AI agents:

npx grexal init --language typescript --name my-agent

If a flag is omitted, the CLI prompts for that value interactively.

Output

Generates:

my-agent/
├── grexal.json              — runtime manifest with sensible defaults
├── agent.py or index.ts     — hello-world entrypoint using the SDK
├── requirements.txt or package.json (+ tsconfig.json for TS)
├── .gitignore               — un-ignores .grexal/agent.json, ignores everything else under .grexal/
└── .grexal/
    ├── agent.json           — { "name": "my-agent" } — flips to { "agentId": "..." } on first push
    └── connections.json     — empty template for local dev credentials

.grexal/agent.json is the local identity binding that ties the project to a specific agent record on the platform (Vercel .vercel/project.json style). It is committed to source control. .grexal/connections.json holds local test credentials and stays gitignored. See Project layout & identity binding below.

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:

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

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):
  >

Flags

For scripting, CI, or AI agents, combine --input and --once for a fully non-interactive run:

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

npx grexal push

Uploads your source to the platform, builds it in a sandbox, and stores the result as a draft deployment. The agent is not made live. You can test the draft from the dashboard ("Test Run" button on the deployment detail page), then grexal publish when ready.

What it does:

1. Validates grexal.json
2. Packages the agent code (respecting .gitignore)
3. Uploads the package to the Grexal platform (authenticated)
4. The platform builds the agent (installs deps, packages artifact)
5. The CLI streams build logs in real-time
6. Reports success (deployment is now succeeded, awaiting publish) or failure

Prerequisites:

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

Flag

Example session

$ npx grexal push

  Pushing stock-analyzer...
  Branch: main
  Commit: a1b2c3d

  Packaging source...
  Package size: 42 KB
  Uploading...

  [build] Build started
  [build] Installing dependencies...
  [build] Dependencies installed
  [build] Packaging artifact...
  [build] Build succeeded. Run `grexal publish` or use the dashboard to make it live.

  Built stock-analyzer v13 successfully.

  Draft deployment ready. Test it from the dashboard, then run `grexal publish` to make it live.

npx grexal publish

Promotes a successful deployment to active. The agent becomes discoverable in the marketplace and can be invoked.

Publishing requires at least one pricing line item. Add one with npx grexal agent price add <unit> <amount> first — publish will error clearly otherwise.

Flags

Example session

$ npx grexal agent price add run_completed 0.05
  Added line item: $0.05 per completed run

$ npx grexal publish
  Published stock-analyzer v13. It's now live.

Rollback

To roll back to an older deployment, publish a specific deploymentId:

npx grexal publish --deployment kd7abc...

Find deployment IDs with npx grexal deployments list (or from the dashboard).

npx grexal unpublish

Takes the agent offline. The active deployment is cleared, status flips back to draft, and the agent disappears from the marketplace. Source and build artifacts are retained — you can re-publish any time.

$ npx grexal unpublish
  Unpublished stock-analyzer. It no longer appears in the marketplace.

npx grexal delete

Permanently takes the agent down. If it's currently published, it's unpublished first; then the record is hidden from the dashboard, the marketplace, and every API. Run history and deployments are retained for billing and audit purposes but are no longer reachable through the developer UI or CLI.

The agent name is reserved — you cannot register a new agent with the same name afterwards. Recovery requires contacting Grexal support.

By default the CLI asks you to type the agent name to confirm. Pass --yes (or -y) to skip the prompt in non-interactive contexts (CI, scripts).

$ npx grexal delete
  This will permanently take down "stock-analyzer".
  The agent will be removed from the marketplace and the dashboard.
  The name "stock-analyzer" will be reserved and cannot be reused.
  Recovery requires contacting Grexal support.

  Type the agent name to confirm: stock-analyzer
  Deleted stock-analyzer. The name is now reserved and cannot be reused.

npx grexal delete --yes

npx grexal deploy

Alias for grexal push --publish — build and publish in one step.

npx grexal deploy

Useful during iteration. For production-bound changes, prefer the two-step flow so you can test before going live.

npx grexal agent

Manages the commercial/listing metadata for your agent — the fields that do NOT live in grexal.json. These are the same fields you can edit from the dashboard; the CLI gives Claude Code or CI pipelines parity with the UI.

The agent identity is read from .grexal/agent.json in the current directory. After the first push it holds { "agentId": "..." }; commands send the id over the wire so the agent is addressable even after a rename. See Project layout & identity binding.

npx grexal agent price <subcommand>

Manages composable, usage-based pricing for your agent. Pricing is a list of line items — each item charges a per-unit USD rate for a platform-measured quantity (run, chars, tokens, pages, image dimensions, file bytes, etc.). The total cost of a run is the sum of all line item subtotals.

Publishing requires at least one line item. Every output-side unit (output_chars, output_tokens, output_file_bytes, output_pdf_pages, output_image, output_audio_seconds, output_video_seconds) must declare --param max_units=<N> as a hard cap.

Supported units:

• Fixed: run_completed
• Input text: input_chars, input_tokens (--param tokenizer=cl100k_base|o200k_base|claude|gemini)
• Input files: input_file_count (--param mimeType=image/* optional), input_file_bytes, input_pdf_pages, input_docx_pages, input_pptx_slides, input_xlsx_rows
• Input media: input_image (--param tier=le_1mp|le_4mp|le_8mp|gt_8mp), input_audio_seconds, input_video_seconds
• Output (requires --param max_units=N): output_chars, output_tokens, output_file_bytes, output_pdf_pages, output_image, output_audio_seconds, output_video_seconds

Tokenizers for claude and gemini are approximations based on a fixed chars-per-token ratio (no public offline tokenizer exists). cl100k_base and o200k_base tokenize exactly via js-tiktoken.

$ npx grexal agent price add run_completed 0.10
  Added line item: $0.10 per completed run

$ npx grexal agent price add input_tokens 0.000002 --param tokenizer=cl100k_base
  Added line item: $0.00 per input token (cl100k (GPT-3.5 / GPT-4))

$ npx grexal agent price add output_pdf_pages 0.05 --param max_units=50
  Added line item: $0.05 per output PDF page (cap: 50)

$ npx grexal agent price list

  stock-analyzer — pricing
    baseline:  Price details
    version:   3
    items:
      [0] $0.10 per completed run
      [1] $0.00 per input token (cl100k (GPT-3.5 / GPT-4))
      [2] $0.05 per output PDF page (cap: 50)

$ npx grexal agent price remove 2
  Removed line item [2]

$ npx grexal agent price clear
  Cleared all line items — agent can no longer be published.

$ npx grexal agent price estimate @./sample-input.json

  stock-analyzer — estimated cost
    estimated: $0.0524
    reserved:  $0.0655 (estimate × 1.25)
    breakdown:
      $0.10 × 1 completed run = $0.10
      $0.00 × 2600 input tokens = $0.0052
      ...

Line item caps: at most 12 items, each amount in [$0.00, $10.00] per unit.

Marketplace sort/filter uses the auto-computed baseline — a median of the agent's most recent 10+ completed organic runs. It resets whenever you change pricing, and shows Price details until enough samples accumulate.

npx grexal agent set-visibility <public|private>

Controls who can discover and run the agent.

• public — listed in the marketplace, anyone can run
• private — only you can run it (default for new agents)

$ npx grexal agent set-visibility public
  Set stock-analyzer visibility to public

npx grexal agent set-description <text>

Update the marketplace description.

$ npx grexal agent set-description "Analyzes stock trends and gives buy/sell recommendations."
  Updated description for stock-analyzer

npx grexal agent set-category <category>

Set the marketplace category. Pass an empty string to clear it.

$ npx grexal agent set-category finance
  Set stock-analyzer category to "finance"

See categories for the supported list.

npx grexal agent set-tags <tags>

Set a comma-separated list of tags. Pass an empty string to clear.

$ npx grexal agent set-tags stocks,finance,trading
  Set stock-analyzer tags to: stocks, finance, trading

npx grexal agent set-name <slug>

Rename the agent. The new slug must be lowercase alphanumeric with hyphens or underscores (start with alphanumeric). Public links are id-based, so renaming doesn't break anything.

$ npx grexal agent set-name stock-pulse
  Renamed agent to stock-pulse

The local .grexal/agent.json continues to hold the same { "agentId": "..." }; the slug stored on the agent record is what changed.

npx grexal agent set-homepage <url>

Set the marketplace homepage link. Pass an empty string to clear.

$ npx grexal agent set-homepage https://example.com
  Set stock-analyzer homepage to https://example.com

npx grexal agent set-repository <url>

Set the marketplace repository link. Pass an empty string to clear.

$ npx grexal agent set-repository https://github.com/you/stock-analyzer
  Set stock-analyzer repository to https://github.com/you/stock-analyzer

npx grexal agent set-icon <path>

Upload a new agent icon. Supported formats: PNG, SVG, JPG, WEBP (max 256 KB). The file is uploaded to the platform and the agent record's icon URL is updated atomically; the previous icon (if any) is replaced.

$ npx grexal agent set-icon ./icon.png
  Uploaded icon for stock-analyzer
  URL: https://...

Requires the agent to have been pushed at least once (.grexal/agent.json must hold an agentId). The icon endpoint addresses by id only.

npx grexal agent set-is-open-source <true|false>

Mark the agent's source as publicly available (or not). Accepts true/false, yes/no, 1/0. Pair with set-repository to point at the source.

$ npx grexal agent set-is-open-source true
  Set stock-analyzer is_open_source to true

npx grexal agent show

Print the agent's current platform-side state.

$ npx grexal agent show

  stock-analyzer
    id:          kd7abc123...
    status:      active
    visibility:  public
    pricing:     Typical: $0.0525 · varies
                 · $0.10 per completed run
                 · $0.00 per input token (cl100k (GPT-3.5 / GPT-4))
    description: Analyzes stock trends and gives buy/sell recommendations.
    category:    finance
    tags:        stocks, finance, trading
    homepage:    https://example.com
    repository:  https://github.com/you/stock-analyzer
    open source: yes
    active:      kd7abc123...

# Parseable for scripts and AI coding agents:
npx grexal agent show --json

npx grexal deployments

Inspects the agent's deployment history. The agent identity is read from .grexal/agent.json in the current directory.

npx grexal deployments list

Lists the agent's deployments (up to 50 most recent) with their IDs, versions, status, commit, and age. The currently active deployment is marked with *active.

$ npx grexal deployments list

  Deployments for stock-analyzer:

    v3  succeeded  j970sbez0vzvx77bdc27ewx3w985ahfj  8717abae  4m ago *active
    v2  succeeded  j97cx9bkq6htstft77wkxcfh0185at6h  8717abae  5m ago
    v1  succeeded  j97cjkjabcq1q61rcv1pt37nmd8594vr  c95eb4c2  16h ago

  Publish an older version:  grexal publish --deployment <id>

Use the listed IDs with grexal publish --deployment <id> to roll back to an older version.

npx grexal runs

Invokes deployed agents and inspects past runs. Like agent and deployments, the agent identity is read from .grexal/agent.json in the current directory.

npx grexal runs invoke

Starts a run on the currently published deployment, then streams the run's logs (stdout, stderr, system, agent) until the run terminates and prints the final result. Authorization is the same as the dashboard "Test Run" button — only the agent's developer can invoke it via the CLI.

Task input must be valid JSON. Provide it via --input '<json>', --input-file <path>, or piped to stdin (in that order of precedence).

If the agent declares connections that aren't set up, runs invoke prompts you for the missing fields before submitting. While the run is following, if it pauses for a connection or a ctx.requestUserAction(...) URL handoff, the CLI surfaces the prompt inline so you can resolve it without leaving the terminal. In a non-TTY shell (CI), the CLI prints the resolution hint and exits non-zero rather than hanging — provision credentials ahead of time with grexal connections set --field ….

$ npx grexal runs invoke --input '{"ticker": "AAPL"}'

  Invoking stock-analyzer...
  Submitted run jh7abc123... against v13

  [system] Run started
  [stdout] Fetching price data...
  [stdout] Analyzing trends...
  [agent]  Recommendation drafted

  Result:
  {
    "recommendation": "buy",
    "confidence": 0.82
  }

# Read input from a file
npx grexal runs invoke --input-file ./test-input.json

# Pipe input from another command or shell heredoc
echo '{"ticker": "AAPL"}' | npx grexal runs invoke

# Test a draft deployment before publishing
npx grexal runs invoke --deployment kd7abc123... --input '{"ticker": "AAPL"}'

# Fire-and-forget; tail later
npx grexal runs invoke --input '{"ticker": "AAPL"}' --no-follow

npx grexal runs list

Lists the most recent runs for the agent (default 20), newest first.

$ npx grexal runs list

  Recent runs for stock-analyzer:

    completed  v13  jh7abc123def456...  just now
    failed     v13  jh7zzz999yyy888...  2m ago
    completed  v12  jh7old111old222...  1h ago

  Tail logs:  grexal runs logs <runId> --follow

npx grexal runs logs <runId>

Prints all logs for a specific run plus the run's status and final result (or error). With --follow, polls until the run reaches a terminal state — useful when the run was started with --no-follow or is still in progress.

$ npx grexal runs logs jh7abc123def456...

  Run jh7abc123def456...
    status:  completed
    started: 2026-04-25T15:42:01.123Z
    ended:   2026-04-25T15:42:04.331Z

  [system] Run started
  [stdout] Fetching price data...
  [stdout] Analyzing trends...
  [agent]  Recommendation drafted

  Result:
  {"recommendation": "buy", "confidence": 0.82}

npx grexal connections

Manages saved credentials for connections declared in grexal.json. The CLI uses the same encrypted store as the dashboard's connections panel. Use these commands to provision required connections before invoking, or to script setup in CI.

If you don't run these manually, grexal runs invoke will detect any missing required connection (either before submitting or once the run is paused waiting on input) and prompt you for the credentials inline.

npx grexal connections list

Lists every saved connection, the agents you've granted access to, and when each was last updated. No plaintext field values are ever returned.

$ npx grexal connections list

  Saved connections:

    openai
      display:  OpenAI API
      fields:   api_key
      granted:  stock-analyzer, summarizer
      updated:  2h ago

npx grexal connections set <connectionId>

Saves credentials for a connection declared in the current agent's grexal.json and grants the agent permission to use them. By default the CLI prompts for each missing field; secret fields are masked. The agent identity is read from .grexal/agent.json in the current directory.

# Interactive — prompts for every missing field
npx grexal connections set openai

# Scripted (CI) — provide every field up front
npx grexal connections set openai --field api_key=$OPENAI_API_KEY

npx grexal connections grant <connectionId>

Grants the current agent permission to use a connection whose credentials you've already saved (e.g. for another agent). No prompt — fails fast if the connection isn't saved yet.

npx grexal connections remove <connectionId>

Removes a saved connection (and all its grants). Pass --field <name> to remove a single field instead of the whole connection.

# Drop everything
npx grexal connections remove openai

# Drop just one field (the connection stays if other fields remain)
npx grexal connections remove openai --field organization_id

npx grexal env

Manages encrypted environment variables for the current agent. Variables are stored per-agent on the platform, encrypted at rest with AWS KMS, and injected into the sandbox at runtime as standard environment variables (e.g. process.env.OPENAI_API_KEY).

The agent identity is read from .grexal/agent.json in the current directory. The agent must have been pushed at least once.

npx grexal env set <NAME> <VALUE>

Set or update an environment variable.

$ npx grexal env set OPENAI_API_KEY sk-abc123
  Set OPENAI_API_KEY for my-agent

Variable names must be uppercase letters, digits, and underscores only ([A-Z_][A-Z0-9_]*). Names starting with GREXAL_ are reserved and rejected.

npx grexal env get <NAME>

Retrieve and display the decrypted value of a variable.

$ npx grexal env get OPENAI_API_KEY
  OPENAI_API_KEY=sk-abc123

npx grexal env list

List all environment variable names for the agent (values are not shown).

$ npx grexal env list

  Environment variables for my-agent:
    OPENAI_API_KEY    updated 2h ago
    DATABASE_URL      updated 3d ago

npx grexal env remove <NAME>

Remove an environment variable.

$ npx grexal env remove DATABASE_URL
  Removed DATABASE_URL from my-agent

Local development

During grexal dev, environment variables are loaded from a .env file in the agent's project directory instead. Platform-stored env vars (set via grexal env set) are only injected in production sandbox runs.

npx grexal validate

Standalone validation of grexal.json. Checks:

• grexal.json exists and has all required fields
• Entrypoint file exists
• Resource limits are within platform maximums
• Connection declarations are well-formed

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.

Project layout & identity binding

A Grexal agent project has two files of metadata, with deliberately separate jobs:

Marketplace metadata (description, category, tags, homepage, repository, icon, open-source flag, pricing, visibility) lives on the agent record on the platform and is mutated via grexal agent set-*. Putting any of those fields in grexal.json is a hard validation error.

Lifecycle of .grexal/agent.json

1. grexal init --name <slug> writes { "name": "<slug>" }.
2. The first grexal push claims the slug server-side, mints an opaque agentId, and the CLI rewrites the file to { "agentId": "<id>" }.
3. From that point every CLI command sends X-Grexal-Agent-Id over the wire — the agent stays addressable across renames (grexal agent set-name).

If you've never run grexal push, identity-aware commands like grexal agent set-description will exit with:

Error: No agent yet on the platform. Run `grexal push` first…

If .grexal/agent.json is missing entirely (e.g. you cloned a repo where it wasn't committed):

Error: No agent identity. Run `grexal init --name <slug>` first…

Both messages tell you exactly which command unblocks the next step.

.gitignore template

grexal init generates a .gitignore that hides everything under .grexal/ by default and explicitly un-ignores agent.json:

.grexal/*
!.grexal/agent.json

This keeps connections.json (local dev credentials) private while letting agent.json ship with the repo.

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.

Typical workflows

First-time publish

npx grexal login
npx grexal init --language typescript --name my-agent
cd my-agent

# Iterate locally
npx grexal dev

# When ready to go live:
npx grexal push                       # build + upload as a draft (claims the slug, mints agentId)
# (optionally test from the dashboard)

# Required by the publish gate — without these, `grexal publish` fails with a
# structured error listing each missing field paired with the exact set-*
# command to fix it.
npx grexal agent set-description "What the agent does, in one sentence."
npx grexal agent set-category <category-slug>
npx grexal agent set-tags a,b,c
npx grexal agent price add run_completed 0.05

npx grexal agent set-visibility public
npx grexal publish                    # go live

Iteration (you already own the agent)

# Fast path — skip the staging step during day-to-day work
npx grexal deploy

Production change (validate before publishing)

npx grexal push                       # builds a draft
# Click "Test Run" on the new deployment in the dashboard
# Confirm the new behavior works as expected
npx grexal publish                    # promote to active

Rollback

npx grexal deployments list              # find the deployment ID to revert to
npx grexal publish --deployment kd7abc123...

What the CLI does not do

• 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.
• Delete agents — use the dashboard.