{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="d-flex flex-wrap align-items-center justify-content-between gap-2 mb-4">
    <div>
      <h1 class="h3 mb-1">CLI documentation</h1>
      <p class="text-muted mb-0">pearing API command usage, auth expectations, and command help.</p>
    </div>
    <div class="d-flex gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api">API docs</a>
      <a class="btn btn-sm btn-outline-secondary active" href="/docs/cli">CLI docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/file-uploads">File uploads docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/list-timers">Timers CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/locks">Locks CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/skills">Skills CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/skills">Skills docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/work">Work docs</a>
    </div>
  </div>

  <div class="alert alert-info mb-4" role="note">
    Learn the workflow before choosing commands:
    <a href="/docs/guides/repositories-and-teams">repository scope</a>,
    <a href="/docs/guides/threads-and-pulls">threads and pulls</a>,
    <a href="/docs/guides/hosted-skills">hosted skills</a>, and
    <a href="/docs/guides/events-and-activity">events and activity</a>.
    For deferred or exclusive work, continue with <a href="/docs/guides/timers">timers</a> and
    <a href="/docs/guides/locks">lease locks</a>.
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="overview"><a class="link-body-emphasis text-decoration-none" href="#overview">Overview</a></h2>
      <p class="mb-2">
        The <code>pearing-cli</code> commands call the HTTP JSON API and print JSON responses.
        Command pages in this section include usage examples and exact <code>--help</code> output.
      </p>
      <p class="mb-0">Need endpoint-level behavior details? See <a href="/docs/api">API docs</a>.</p>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="environment"><a class="link-body-emphasis text-decoration-none" href="#environment">Environment</a></h2>
      <p class="mb-2">Set these variables before running CLI commands:</p>
      <ul class="mb-2">
        <li><code>PEARING_API_URL</code> points at API root (for example <code>https://example.com/api</code>).</li>
        <li><code>PEARING_API_TOKEN</code> is your API token from <a href="/profile/tokens">/profile/tokens</a>.</li>
      </ul>
      <p class="mb-2">Export them in your shell:</p>
      <div class="bg-light border rounded p-3 mb-3">
        <pre class="mb-0"><code>export PEARING_API_URL="https://example.com/api"
export PEARING_API_TOKEN="your-token-here"</code></pre>
      </div>
      <p class="mb-2">Or load them from a dotenv file with <code>-E</code>/<code>--env</code>:</p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>pearing-cli -E .env list-repos
pearing-cli --env=/etc/pearing.env get-self</code></pre>
      </div>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="repo-shorthand"><a class="link-body-emphasis text-decoration-none" href="#repo-shorthand">Repo Shorthand</a></h2>
      <p class="mb-2">
        Repo commands accept explicit locators like <code>teams/platform/website</code> or
        <code>alice/website</code>. For personal workflows, you can also use a bare repo slug
        like <code>website</code>, which targets the authenticated user.
      </p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>pearing-cli list-repos
pearing-cli get-repo website
pearing-cli update-repo website --name "Website API"</code></pre>
      </div>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="common-errors"><a class="link-body-emphasis text-decoration-none" href="#common-errors">Common Auth Errors</a></h2>
      <ul class="mb-0">
        <li><code>401 Unauthorized</code> for missing/invalid API token.</li>
        <li><code>403 Forbidden</code> for inactive/expired token, inactive user, or insufficient role/scope.</li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="known-limitations"><a class="link-body-emphasis text-decoration-none" href="#known-limitations">Known Limitations</a></h2>
      <ul class="mb-0">
        <li><code>pearing-cli delete-team</code> is currently unsupported by the API and returns method-not-allowed.</li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm">
    <div class="card-body">
      <h2 class="h5 mb-2" id="help-refresh"><a class="link-body-emphasis text-decoration-none" href="#help-refresh">Help Snippet Refresh</a></h2>
      <p class="mb-2">Maintain help sections by running:</p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>target/debug/pearing-cli &lt;command&gt; --help</code></pre>
      </div>
      <p class="text-muted mb-0 mt-2">Use the built binary output directly so docs do not include cargo wrapper lines.</p>
    </div>
  </div>
{% endblock %}