> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novita.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke

The CLI's `agent invoke` command sends a payload to a deployed Novita Agent and returns its response. It supports both plain-text prompts and structured JSON input, and can stream the response as it is produced.

> [!NOTE]
>
> **Note:** Invoke runs from a deployed agent's project directory. It requires a `novita.toml` in the current directory (created by `agent launch`) and the `NOVITA_API_KEY` environment variable.

***

## Prerequisites

```bash CLI icon="terminal" theme={"system"}
export NOVITA_API_KEY=<your API key>

# The agent must already be deployed (run from its project directory)
# novita agent launch
```

***

## Usage

```bash CLI icon="terminal" theme={"system"}
novita agent invoke <payload> [options]
```

| Argument / Option | Description |
| - | - |
| `<payload>` | JSON payload or prompt text (required) |
| `--agentId <id>` | Agent ID to invoke, in the form `agent_name-template_id` |
| `--stream` | Stream the response as it is generated |
| `--timeout <seconds>` | Request timeout in seconds (default: 60) |
| `--env <key=value>` | Environment variable for this invocation. Repeatable |
| `--verbose` | Verbose output |

***

## Payload

The `<payload>` is parsed as JSON if possible; otherwise it is treated as plain prompt text.

* A **string** is wrapped as `{ "query": "...", "prompt": "..." }`.
* A **JSON object** is passed through; if it has `query` but no `prompt`, `prompt` is filled in from `query`.

***

## Agent ID & environment variables

The command resolves which agent to call and what env vars to pass as follows:

| Item | Resolution |
| - | - |
| Agent ID | `--agentId` if given; otherwise `status.agent_id` from `.novita-agent.yaml` |
| Env vars | `spec.envVars` in `.novita-agent.yaml` merged with `--env` — CLI values override the config file |

***

## Streaming vs non-streaming

Without `--stream`, the command waits for the full result and prints the agent ID, session ID, execution time, and the response body. With `--stream`, output chunks are written to the terminal as they arrive.

***

## Examples

```bash CLI icon="terminal" theme={"system"}
novita agent invoke "Summarize today's news"
```

```bash CLI icon="terminal" theme={"system"}
novita agent invoke '{"query": "list files", "path": "/tmp"}'
```

```bash CLI icon="terminal" theme={"system"}
novita agent invoke "Analyze this repo" \
  --agentId my-agent-tpl_123 \
  --stream \
  --env LOG_LEVEL=debug \
  --timeout 120
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.