> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/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.
</Note>

***

## 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-sandbox-cli agent launch
```

***

## Usage

```bash CLI icon="terminal" theme={"system"}
novita-sandbox-cli 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-sandbox-cli agent invoke "Summarize today's news"
```

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

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