# list

List installed artifacts

Canonical URL: https://docs.asterdoc.com/cli/commands/list/

Lists all artifacts installed in the current project.

## Usage

```bash
asterdoc list [options]
asterdoc ls [options]
```

## Options

| Option          | Description                                                        |
| --------------- | ------------------------------------------------------------------ |
| `--json`        | Output as JSON                                                     |
| `--kind <kind>` | Filter by artifact kind: `form`, `document`, `checklist`, `bundle` |

## Description

The `list` command reads the project's lock file and displays all installed artifacts, grouped by namespace. It shows the artifact name, the edition when the artifact has one, the version, and the number of downloaded layers. In JSON output, an artifact that has editions also carries `edition`.

## Examples

List all installed artifacts:

```bash
asterdoc list
```

Using the alias:

```bash
asterdoc ls
```

Output as JSON:

```bash
asterdoc list --json
```

## Output

```
Installed artifacts (4):

@acme
  residential-lease v1.0.0 (2 layers)
  w4 2025 v1.0.0
  w9 v1.0.0 (1 layer)

@internal
  employee-onboarding v2.1.0
```

When no artifacts are installed:

```
No artifacts installed.
Run 'asterdoc add @namespace/artifact-name' to install one.
```

## JSON output

```json
[
  {
    "ref": "@acme/residential-lease",
    "version": "1.0.0",
    "output": "json",
    "path": "artifacts/@acme/residential-lease.json",
    "installedAt": "2025-01-15T10:30:00.000Z",
    "layers": ["pdf", "markdown"]
  },
  {
    "ref": "@acme/w4",
    "edition": "2025",
    "version": "1.0.0",
    "output": "json",
    "path": "artifacts/@acme/w4.json",
    "installedAt": "2025-01-15T10:31:00.000Z",
    "layers": []
  }
]
```

## See also

* [add](/cli/commands/add) - Install an artifact
* [show](/cli/commands/show) - View artifact details