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

# cowboy build

> Produce every artifact a deployment needs, in order

## Synopsis

```bash theme={null}
cowboy build [<target>] [--list-files] [--json]
             [--base-rootfs <dir> | --update-base] [--expected-base-digest <hex>]
```

## Behavior

1. Discover the project and select the target: the one named, the project's only actor, or every target when several exist and none is named.
2. For a target that uses off-chain functions, build the off-chain image first and write its proxy; the actor compiles against the generated proxy, and the proxy pins the image digest, so a stale proxy cannot survive this command.
3. Compile the actor artifact and apply the same source rules as `cowboy check`.
4. Write the artifact and its manifest to `.cowboy/build/<target>` and print `Built actor target '<name>'.` with the artifact path, code hash, and build identity. Off-chain targets also print the image digest, the written and unchanged files, and the exported function signatures.

Under `--json` the result flattens the `cowboy check` result and adds `output_directory`, `files`, and, for off-chain targets, an `offchain` object (image lock, packages, exports, written/unchanged paths, credential-like paths that were excluded, source file counts, and, with `--list-files`, every path that will be published).

## Flags

| Flag | Default | Description |
| - | - | - |
| `<target>` | Inferred when the project has one actor | Actor target name |
| `--list-files` | `false` | Print every file the off-chain image will publish, not just the top-level entries |
| `--json` | `false` | Emit one versioned JSON result object |
| `--base-rootfs` | `COWBOY_OFFCHAIN_BASE_ROOTFS` | Advanced: unpacked `cby-runner-python` base rootfs to compose onto |
| `--update-base` | `false` | Refresh the tracked `offchain.lock` base from the active named base; conflicts with `--base-rootfs` |
| `--expected-base-digest` | None | Advanced: digest the base rootfs must hash to (32 bytes, hex) |

## Example

```bash theme={null}
$ cowboy build
✓ Built actor target 'demo'.
  Actor artifact: .cowboy/build/demo/actor.py
  Code hash: 0x9c0d...
  Build identity: a3626f6bf5...
```

## Edge Cases

* The off-chain flags (`--base-rootfs`, `--expected-base-digest`, `--list-files`) are refused when the selected target does not use off-chain functions.
* Files whose names look like credentials are excluded from the image and listed as `excluded (credential-like): <path>`.
* Rule violations fail the build with exit code 1 and every broken rule reported.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.