{% extends "docs/base.html" %}
{% block docs_content %}
<h1 class="h3 mb-2">Locks CLI</h1>
<p>Use lease locks from scripts and agents. Omit scope flags for your user scope; pass <code>--team</code> for a team or <code>--repo</code> for a repository.</p>
<div class="alert alert-info mb-4" role="note">
  Learn the ownership boundaries in the <a href="/docs/guides/locks">Lease locks guide</a>, then see
  <a href="/docs/guides/coordinate-concurrent-agents">how duplicate responders coordinate</a>.
</div>
<pre><code>pearing-cli acquire-lock deploy --request-uuid "$REQUEST_UUID" --lease-seconds 60 --wait-seconds 30 --repo teams/platform/app
pearing-cli get-lock-ticket deploy "$TICKET_UUID" --repo teams/platform/app
pearing-cli heartbeat-lock-ticket deploy "$TICKET_UUID" --lease-seconds 60 --repo teams/platform/app
pearing-cli release-lock-ticket deploy "$TICKET_UUID" --repo teams/platform/app</code></pre>
<p><code>acquire-lock</code> generates a request UUID when omitted, but retries should preserve an explicit UUID. Poll queued tickets, heartbeat held tickets at one third of their lease, and always release. The JSON response carries status, lease expiry, exact queue position, and fence token.</p>
<p>Persist and compare the fence token atomically in the protected external system. Pearing coordinates work but cannot stop stale external work after a lease expires.</p>
<p>Team locks require active membership; repo locks require maintainer access. Release remains available to a ticket owner after access is revoked.</p>
{% endblock %}