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

# Tools

> Search, inspect, and execute tools from the command line.

The core CLI workflow is: **search → execute → if auth error → connect → retry**.

## Search for Tools

```bash theme={null}
danube search "send an email"
```

Filter by service:

```bash theme={null}
danube search "send message" --service slack
```

Limit results:

```bash theme={null}
danube search "analytics" --limit 5
```

## Execute a Tool

By ID:

```bash theme={null}
danube execute a1b2c3d4-5678-90ab-cdef-1234567890ab -d '{"to": "user@example.com"}'
```

By slug:

```bash theme={null}
danube execute gmail-send-email -d '{"to": "user@example.com", "subject": "Hello"}'
```

By exact name:

```bash theme={null}
danube execute "Gmail - Send Email" -d '{"to": "user@example.com", "subject": "Hello"}'
```

Resolution is exact, never fuzzy. A slug is looked up first; otherwise the name is compared to the search results with case and punctuation ignored (`gmail-send-email` and `Gmail - Send Email` are the same key) and must match exactly one tool. Anything else exits 1 with `error: not_found` and a `candidates` list of `name`, `id` and `slug` to pick from; nothing is executed. Check what a reference resolves to with `--dry-run`, which prints `tool_id`, `tool_name` and `resolved_by` (`uuid`, `slug` or `name`).

## Data Input (`-d` flag)

The `-d` flag accepts multiple formats:

<CodeGroup>
  ```bash Inline JSON theme={null}
  danube execute gmail-send-email -d '{"to": "user@example.com", "subject": "Hello"}'
  ```

  ```bash From file theme={null}
  danube execute gmail-send-email -d @params.json
  ```

  ```bash From stdin theme={null}
  echo '{"to": "user@example.com"}' | danube execute gmail-send-email -d -
  ```
</CodeGroup>

## Get Schema

Inspect a tool's parameter schema before executing:

```bash theme={null}
danube execute "Gmail - Send Email" --get-schema
```

## Dry Run

Validate parameters without executing:

```bash theme={null}
danube execute gmail-send-email --dry-run -d '{"to": "user@example.com"}'
```

## Connect to a Service

If execution fails with an auth error, the CLI tells you what to run:

```bash theme={null}
# This might fail with: "Run 'danube connect gmail' first"
danube execute gmail-send-email -d '{"to": "user@example.com"}'

# Connect and retry
danube connect gmail
danube execute gmail-send-email -d '{"to": "user@example.com"}'
```

## Batch Execute

Execute up to 10 tools from a JSON file:

```json theme={null}
[
  {"tool_id": "a1b2c3d4", "tool_input": {"to": "user@example.com"}},
  {"tool_id": "e5f6g7h8", "tool_input": {"channel": "#team"}}
]
```

```bash theme={null}
danube tools batch calls.json
```

## Tool Info

Get full details for a specific tool:

```bash theme={null}
danube tools info a1b2c3d4
```

## Agent Usage

Agents call the CLI via subprocess. When stdout is piped (not a TTY), output defaults to JSON automatically:

```python theme={null}
import subprocess, json

result = subprocess.run(
    ["danube", "search", "send email"],
    capture_output=True, text=True
)
tools = json.loads(result.stdout)

result = subprocess.run(
    ["danube", "execute", tools[0]["id"],
     "-d", json.dumps({"to": "user@example.com"})],
    capture_output=True, text=True
)
output = json.loads(result.stdout)
```

## Unix Pipe Examples

```bash theme={null}
# Find and execute first matching tool
danube search "weather" | jq '.[0].id' -r | \
  xargs -I{} danube execute {} -d '{"city": "Oslo"}'

# Chain tool outputs
danube execute analytics-summary -d '{"date": "2026-03-28"}' | \
  jq -r '.result.summary' | \
  xargs -I{} danube execute slack-send -d "{\"text\": \"{}\"}"
```