# Resource CLI Reference

The `agents resource` command group manages resource types and resource
instances in the CleverAgents resource registry.

## Resource Instance Commands

### `agents resource add`

Add a new resource instance of a given type.

```bash
agents resource add git-checkout local/my-repo --path /home/user/repo
agents resource add fs-directory local/data --path /data --read-only
```

### `agents resource list`

List registered resources with optional type filter.

```bash
agents resource list
agents resource list --type git-checkout
agents resource list --format json
```

### `agents resource show`

Show details of a specific resource by name or ULID.

```bash
agents resource show local/my-repo
agents resource show 01HXYZ1234567890ABCDEFGHIJ
```

### `agents resource remove`

Remove a resource from the registry.

```bash
agents resource remove local/my-repo
agents resource remove --yes local/my-repo
```

### `agents resource tree`

Display a resource and its children as a tree (DAG). Output is
deterministically ordered by resource name.

**Options:**

| Option       | Description                              |
|--------------|------------------------------------------|
| `--depth N`  | Maximum tree depth (-1 for unlimited)    |
| `--type TYPE`| Filter children by resource type         |
| `--format`   | Output format (json/yaml/plain/table/rich) |

**Examples:**

```bash
# Show full tree
agents resource tree local/my-repo

# Limit depth to 2 levels
agents resource tree local/my-repo --depth 2

# Show only fs-directory children
agents resource tree local/my-repo --type fs-directory

# JSON output
agents resource tree local/my-repo --format json
```

### `agents resource inspect`

Show detailed information about a resource. Optionally display
the child tree or read file content.

**Options:**

| Option          | Description                                  |
|-----------------|----------------------------------------------|
| `--tree`        | Also show child tree                         |
| `--file PATH`   | Show file content (for git-checkout/fs-mount) |
| `--format`      | Output format (json/yaml/plain/table/rich)   |

**Examples:**

```bash
# Basic inspect
agents resource inspect local/my-repo

# Inspect with child tree
agents resource inspect local/my-repo --tree

# Read a file from a git-checkout resource
agents resource inspect local/my-repo --file README.md

# JSON output
agents resource inspect local/my-repo --format json
```

### `agents resource link-child`

Create a DAG edge between two resources (parent -> child). The
child's resource type must be allowed by the parent's type
constraints. Cycles are rejected.

**Examples:**

```bash
agents resource link-child local/my-repo local/my-dir
agents resource link-child local/my-repo local/my-dir --format json
```

### `agents resource unlink-child`

Remove a DAG edge between two resources. Requires confirmation
unless `--yes` is passed.

**Options:**

| Option    | Description               |
|-----------|---------------------------|
| `--yes`   | Skip confirmation prompt  |
| `--format`| Output format             |

**Examples:**

```bash
agents resource unlink-child local/my-repo local/my-dir
agents resource unlink-child --yes local/my-repo local/my-dir
```

## Resource Type Commands

### `agents resource type add`

Register a custom resource type from a YAML configuration file.

```bash
agents resource type add --config ./resource-types/my-type.yaml
```

### `agents resource type list`

List all registered resource types (built-in and custom).

```bash
agents resource type list
agents resource type list --format json
```

### `agents resource type show`

Show details of a registered resource type.

```bash
agents resource type show git-checkout
agents resource type show --format json local/my-type
```

### `agents resource type remove`

Remove a custom resource type. Built-in types cannot be removed.

```bash
agents resource type remove local/my-type
agents resource type remove --yes local/my-type
```