# diff

Compare two artifacts

Canonical URL: https://docs.paradoc.dev/cli/commands/diff/

Shows differences between two artifact files.

## Usage

```bash
paradoc diff <file1> <file2> [options]
```

## Arguments

| Argument | Description                     |
| -------- | ------------------------------- |
| `file1`  | First artifact file to compare  |
| `file2`  | Second artifact file to compare |

## Options

| Option        | Description                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `--name-only` | Print the paths of the two files when they differ, and nothing when they are identical (no content diff) |

## Description

The `diff` command compares two artifact files and displays the differences in unified diff format. It attempts to parse both files as artifacts to show artifact names in the output.

## Exit status

Like POSIX `diff`, the exit status tells scripts and agents whether the files differ, without reading the output:

| Status | Meaning                                   |
| ------ | ----------------------------------------- |
| `0`    | The files are identical                   |
| `1`    | The files differ                          |
| `2`    | An error occurred, such as a missing file |

## Examples

Compare two files:

```bash
paradoc diff form-v1.yaml form-v2.yaml
```

Check if files differ in a script:

```bash
paradoc diff form-v1.yaml form-v2.yaml --name-only > /dev/null
case $? in
  0) echo "unchanged" ;;
  1) echo "form changed" ;;
  *) echo "diff failed" ;;
esac
```

## Output

When files differ:

```
--- lease-agreement (form)
+++ lease-agreement (form)

@@ -5,7 +5,7 @@
 version: 1.0.0
 title: Residential Lease Agreement
 fields:
-  monthlyRent:
+  rentAmount:
     type: money
     label: Monthly Rent
     required: true
```

When files are identical:

```
Files are identical
```

With `--name-only`, when files differ:

```
form-v1.yaml
form-v2.yaml
```

## See also

* [apply](/cli/commands/apply) - Apply a patch file
* [show](/cli/commands/show) - Display artifact content

The output is a human-readable unified-diff display. Its annotated file headers are not an input format for `paradoc apply`; use `git diff` or `diff -u` to create an applicable patch.