# swarmfile-brlock

`swarmfile-brlock` drives the engine's byte-range lock API directly. It talks to a **running engine** over its control socket, so start the engine (or the Desktop App) first. It's a developer/integrator tool - a test client for the same lock primitive that a native worksharing app plugin (the kind of Revit-class CAD/BIM integration that needs to lock only the elements one person is editing, not an entire file) would implement against. It is not something a typical end user runs day to day, and **no installer ships it**: build it from a checkout when you're working on an integration (`cargo build -p swarmfile-engine --bin swarmfile-brlock`).

For the conceptual introduction to byte-range locking and how it differs from a whole-file entry lock, see [Working with Files](https://swarmfile.com/docs/guides/working-with-files).

## Global flags

| Flag | Description |
|---|---|
| `--cache-dir` | Engine cache dir to connect against. Defaults to `$SWARMFILE_CACHE_DIR`, else `~/.cache/swarmfile` (macOS/Linux) or `%LOCALAPPDATA%\swarmfile` (Windows). |

## `acquire`

Acquire an exclusive byte-range lock.

| Flag | Description |
|---|---|
| `--entry-id` | Entry to lock a byte range on |
| `--offset` | Start offset, in bytes (`u64`). Default `0` |
| `--length` | Length of the range, in bytes (`u64`). Default `0`, which means "to end of file," not a zero-length range |
| `--handle-ref` | Handle the lock is tied to |

## `release-handle`

Release every lock tied to a handle ref.

| Flag | Description |
|---|---|
| `--handle-ref` | Handle whose locks should all be released |

## Example: acquire and release a range

A plugin integration would typically acquire a range around the elements being edited, hold it for the duration of the edit, and release everything tied to its handle on close - this simulates that sequence from the command line:

```bash
swarmfile-brlock acquire --entry-id ent_9f2a --offset 4096 --length 512 --handle-ref plugin-session-1

# ...edit is in progress, range is locked...

swarmfile-brlock release-handle --handle-ref plugin-session-1
```

Releasing by handle ref rather than by individual range means a plugin doesn't need to track every range it acquired - closing out a session releases everything that session took.

## Exit codes

Meaningful for scripting a CI/integration test against a real lock denial, which is the tool's main use case:

| Exit code | Meaning |
|---|---|
| `0` | Success. |
| `2` | The lock was denied (a conflicting range is already held). |
| `1` | Any other error. |