cleveragents-core/docs/reference/tool_cli.md

# Tool & Validation CLI Reference

The `agents tool` and `agents validation` command groups manage tools and
validations in the CleverAgents tool registry.

## Tool Commands

### `agents tool add`

Register a tool from a YAML configuration file.

```bash
agents tool add --config ./tools/line-counter.yaml
agents tool add --config ./tools/line-counter.yaml --update
agents tool add --config ./tools/line-counter.yaml --format json
```

**Options:**

| Flag          | Description                          |
|---------------|--------------------------------------|
| `--config`    | Path to YAML configuration file      |
| `--update`    | Update if tool already exists        |
| `--format`    | Output format (json/yaml/plain/table/rich) |

### `agents tool remove`

Remove a tool by namespaced name.

```bash
agents tool remove local/line-counter
agents tool remove --yes local/line-counter
```

**Options:**

| Flag   | Description               |
|--------|---------------------------|
| `--yes`| Skip confirmation prompt  |

### `agents tool list`

List tools with optional filters.

```bash
agents tool list
agents tool list --namespace local
agents tool list --source mcp
agents tool list --type validation
agents tool list "line-.*"
agents tool list --format json
```

**Options:**

| Flag          | Description                              |
|---------------|------------------------------------------|
| `--namespace` | Filter by namespace                      |
| `--source`    | Filter by source type                    |
| `--type`      | Filter by type (tool or validation)      |
| `--format`    | Output format (json/yaml/plain/table/rich) |

### `agents tool show`

Show full details for a tool.

```bash
agents tool show local/line-counter
agents tool show --format json local/line-counter
```

**Options:**

| Flag       | Description                              |
|------------|------------------------------------------|
| `--format` | Output format (json/yaml/plain/table/rich) |

## Validation Commands

### `agents validation add`

Register a validation from a YAML configuration file.

```bash
agents validation add --config ./validations/coverage-check.yaml
agents validation add --config ./validations/coverage-check.yaml --update
```

**Options:**

| Flag          | Description                          |
|---------------|--------------------------------------|
| `--config`    | Path to YAML configuration file      |
| `--update`    | Update if validation already exists  |
| `--format`    | Output format (json/yaml/plain/table/rich) |

### `agents validation attach`

Attach a validation to a resource.

```bash
agents validation attach git-checkout/my-repo local/coverage-check
agents validation attach --project myproj git-checkout/my-repo local/lint
agents validation attach --mode informational resource/r1 local/val1
agents validation attach git-checkout/my-repo local/check threshold=80
```

**Options:**

| Flag        | Description                                    |
|-------------|------------------------------------------------|
| `--project` | Project scope                                  |
| `--plan`    | Plan ID scope                                  |
| `--mode`    | Validation mode (required or informational)    |
| `--format`  | Output format (json/yaml/plain/table/rich)     |

### `agents validation detach`

Detach a validation from a resource.

```bash
agents validation detach 01HXYZ1234567890ABCDEFGHIJ
agents validation detach --yes 01HXYZ1234567890ABCDEFGHIJ
```

**Options:**

| Flag   | Description               |
|--------|---------------------------|
| `--yes`| Skip confirmation prompt  |
| `--format` | Output format (json/yaml/plain/table/rich) |

## YAML Configuration Examples

### Tool Configuration

```yaml
name: local/line-counter
description: Count lines in a file
source: custom
code: |
  def run(inputs):
      with open(inputs["path"]) as f:
          return {"count": sum(1 for _ in f)}
input_schema:
  type: object
  properties:
    path:
      type: string
capability:
  read_only: true
  idempotent: true
timeout: 60
```

### Validation Configuration

```yaml
name: local/coverage-check
description: Check code coverage meets threshold
source: custom
mode: required
code: |
  def run(inputs):
      return {"passed": inputs["coverage"] >= inputs.get("threshold", 80)}
```

### Wrapped Validation

```yaml
name: local/lint-check
description: Run linting as a validation
source: wrapped
wraps: local/run-lint
transform: |
  def transform(result):
      return {"passed": result.get("exit_code") == 0}
mode: informational
```