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

# crewship invoke

> Run your deployed crew

## Usage

```bash theme={null}
crewship invoke [options]
```

## Description

Triggers a new run of your deployed crew. You can pass input data and stream events in real-time.

## Options

| Option                | Description                                       |
| --------------------- | ------------------------------------------------- |
| `--name`, `-n`        | Deployment name (for multi-deployment configs)    |
| `--input <json>`      | JSON input to pass to your crew                   |
| `--input-file <path>` | Read input from a JSON file                       |
| `--stream`            | Stream events in real-time                        |
| `--project <name>`    | Project to invoke (defaults to current directory) |
| `--deployment <id>`   | Specific deployment to run (defaults to latest)   |
| `--wait`              | Wait for completion and show result               |
| `--timeout <seconds>` | Maximum time to wait (default: 300)               |

## Examples

### Basic invocation

```bash theme={null}
crewship invoke --input '{"topic": "AI agents"}'
```

Output:

```
▶ Run started: run_abc123xyz
  Status: running

Use `crewship runs get run_abc123xyz` to check status.
```

### Stream events

```bash theme={null}
crewship invoke --input '{"topic": "quantum computing"}' --stream
```

Real-time output:

```
▶ Run started: run_abc123xyz
├─ [10:30:01] Researcher agent starting task...
├─ [10:30:15] Tool: web_search("quantum computing breakthroughs 2024")
├─ [10:30:18] Researcher agent completed task
├─ [10:30:19] Writer agent starting task...
├─ [10:30:45] Writer agent completed task
├─ [10:30:46] Artifact: research_report.md (4.2 KB)
✅ Run completed in 45.2s
```

### Input from file

```bash theme={null}
# Create input file
echo '{"topic": "machine learning", "style": "technical"}' > input.json

# Invoke with file
crewship invoke --input-file input.json
```

### Wait for result

```bash theme={null}
crewship invoke --input '{"query": "test"}' --wait
```

The CLI waits for completion and shows the final result:

```
▶ Run started: run_abc123xyz
⏳ Waiting for completion...
✅ Run completed in 32.1s

Result:
{
  "output": "Generated report content...",
  "artifacts": ["report.md"]
}
```

### Invoke a named deployment

```bash theme={null}
# In a multi-deployment project, target a specific deployment
crewship invoke --name research-agent --input '{"topic": "AI agents"}'
```

### Invoke specific deployment

```bash theme={null}
# Invoke a previous deployment (for testing)
crewship invoke --deployment dep_xyz789 --input '{"test": true}'
```

## Input Format

Input must be valid JSON:

```bash theme={null}
# Object
crewship invoke --input '{"key": "value"}'

# With nested data
crewship invoke --input '{"user": {"name": "Alice", "preferences": ["fast", "detailed"]}}'
```

Your crew receives this as the `inputs` parameter:

```python theme={null}
def kickoff(inputs: dict):
    topic = inputs.get("key")
    user_name = inputs.get("user", {}).get("name")
```

## Event Types

When streaming, you'll see these event types:

| Event                 | Description         |
| --------------------- | ------------------- |
| `▶ Run started`       | Run execution began |
| `├─ [time] message`   | Log from your crew  |
| `├─ Tool: name(args)` | Tool was invoked    |
| `├─ Artifact: name`   | File was produced   |
| `✅ Run completed`     | Success             |
| `❌ Run failed`        | Error occurred      |

## Handling Errors

If a run fails:

```bash theme={null}
crewship invoke --input '{"bad": "input"}' --stream
```

```
▶ Run started: run_abc123xyz
├─ [10:30:01] Starting crew execution...
├─ [10:30:02] Error: Missing required field 'topic'
❌ Run failed after 1.2s

Error: CrewExecutionError: Missing required field 'topic'
```

## Programmatic Usage

For scripts and automation:

```bash theme={null}
# Get run ID
RUN_ID=$(crewship invoke --input '{"topic": "test"}' --json | jq -r '.run_id')

# Poll for status
crewship runs get $RUN_ID --json
```

## Related

<CardGroup cols={2}>
  <Card title="Streaming Guide" icon="bolt" href="/guides/streaming">
    Deep dive into event streaming
  </Card>

  <Card title="Artifacts" icon="file-export" href="/guides/artifacts">
    Handle run outputs
  </Card>
</CardGroup>