# CLI reference.

> Thirteen subcommands make up the renest command-line tool — pack, restore, start, doctor, verify, watch, lint, serve, presign, update-rules, list, export and support — and --json makes their output machine-readable. This page lists what each does and the flags that matter.

Canonical page: https://renest.ai/docs-cli.html

<p>Run <code>renest --help</code> on your own install for the authoritative list — this page
follows it, but your version is the one that's true.</p>

<h2 id="pack">pack — seal the setup that worked</h2>

<pre>$ renest pack --dir ./run --workflow workflow-api.json --out ./nests</pre>

<ul>
  <li><code>--dir</code> — the environment root (the folder holding <code>ComfyUI/</code>). Required.</li>
  <li><code>--out</code> — where to write the nest. Required for a real pack; only <code>--dry-run</code> can skip it. It is laid out like the drive: the manifest goes to <code>&lt;out&gt;/nests/&lt;nest-id&gt;/manifest.json</code>, the files under <code>&lt;out&gt;/blobs/</code>.</li>
  <li><code>--workflow</code> — for image runs, the workflow exported in <strong>API format</strong> (ComfyUI: <em>Export (API)</em>). The ordinary saved workflow is refused.</li>
  <li><code>--auto</code> — pack the ComfyUI folder as it stands, with no workflow named.</li>
  <li><code>--framework kohya|llamafactory</code> — for fine-tuning runs instead of a workflow. Needs <code>--run-record</code>, the JSON record of the run that worked.</li>
  <li><code>--dry-run</code> — print the plan, write nothing.</li>
  <li><code>--offline</code> — pack with no network at all. The nest is still a faithful record of this machine, but packages pinned to a vendor-only version (like <code>torch==…+cu124</code>) keep no download address, so it is marked as not rebuildable on another machine. (Pinning those packages to direct wheel links is on by default; <code>--pin-wheels</code> only matters to switch it back on together with <code>--offline</code>.)</li>
  <li><code>--dest hosted</code> — also upload it to your Renest drive (needs an access token, see <a href="#auth">Signing in</a>). <code>--dest s3</code> uploads to a bucket of your own instead.</li>
  <li><code>--mine PATH</code> — declare a file as your own work (a LoRA you trained), so it travels on a hand-off. Files you did not make are treated as restricted by default. Repeatable.</li>
  <li><code>--nest-name</code> — a human name for it.</li>
</ul>

<p>Exactly one of <code>--workflow</code>, <code>--auto</code>, <code>--spec</code> or
<code>--framework</code> tells <code>pack</code> what to capture.</p>

<p>Details and what it deliberately skips: <a href="docs-capture.html">Capture a run</a>.</p>

<h2 id="restore">restore — bring a nest back on this machine</h2>

<pre>$ renest restore --manifest ./nests/nests/&lt;nest-id&gt;/manifest.json --dir ./run</pre>

<ul>
  <li><code>--manifest</code> <em>or</em> <code>--grant</code> — a manifest (file or URL), or a restore code. One of the two.</li>
  <li><code>--dir</code> — where to rebuild. Required.</li>
  <li><code>--plan</code> — check this machine, then list what the rebuild would do (downloads, dependency resolution, and every setup command it would run, in full) and stop before fetching anything. If the machine fails the check, you get the check's verdict and no plan.</li>
  <li><code>--check-only</code> — check whether everything this nest does <em>not</em> carry can still be fetched on this machine, then stop. Needs no GPU, so you can run it on a laptop before renting anything.</li>
  <li><code>--force</code> — proceed despite a blocking pre-flight result.</li>
  <li><code>--no-resume</code> — start clean instead of continuing an interrupted pull.</li>
  <li><code>--reverify</code> — check everything against its fingerprint again, including what an earlier run already confirmed.</li>
  <li><code>--skip-launch</code> — restore files and dependencies without starting the app or running the packed workflow.</li>
  <li><code>--package-source ADDRESS</code> — install dependencies from a closer package index; every package is still checked against the nest.</li>
  <li><code>--no-setup</code> — don't run the setup commands the nest brought with it.</li>
  <li><code>--no-report</code> — don't send progress back to your drive when restoring from a drive-issued code.</li>
  <li><code>--trust-sender</code> / <code>--trust-host</code> — for nests from other people, and for internal mirrors.</li>
</ul>

<p>Details: <a href="docs-restore.html">Restore anywhere</a>.</p>

<h2 id="start">start — run the app the restore brought back</h2>

<pre>$ renest start --dir ./run --listen 0.0.0.0</pre>

<p>A successful restore ends by naming the command that starts the app. <code>start</code>
runs that same command for you: same program from the nest's own environment, same working
folder, same environment variables. Its exit code is the app's. If the app listens on a
port, it says which one — on a rented machine you still have to expose that port in your
provider's panel to reach it from your browser.</p>

<ul>
  <li><code>--dir</code> — the folder you restored into. Defaults to the current folder.</li>
  <li><code>--listen ADDRESS</code> — listen on this address instead of the one recorded. Use <code>0.0.0.0</code> to reach the app from your own browser on a rented box.</li>
  <li><code>--dry-run</code> — print the command it would run, then stop.</li>
</ul>

<p>It only runs what a successful restore recorded. If there is nothing recorded in that
folder — no restore yet, or a nest in an older format — it stops and tells you to run
<code>renest restore</code> instead of guessing a command. If <code>renest --help</code> on
your install doesn't list <code>start</code>, your copy predates it: use the command the
restore's closing lines print.</p>

<h2 id="auth">Signing in to your drive</h2>

<p><strong>list</strong>, <strong>export</strong> and <code>pack --dest hosted</code> talk to your
Renest drive, so they need an access token. Generate one in the web console, then give it to
the tool in one of two ways:</p>

<ul>
  <li><strong>Environment variable</strong> — <code>export RENEST_TOKEN=…</code> for the
  current shell. If it is set, it wins.</li>
  <li><strong>Config file</strong> — put it in your user config file, under
  <code>[auth]</code>:
  <pre>[auth]
token = "rnt_…"</pre>
  The file is <code>&#126;/.config/renest/config.toml</code> on Linux and
  <code>&#126;/Library/Application Support/renest/config.toml</code> on macOS;
  <code>--config PATH</code> points the tool at a different file. It is a plain-text secret,
  so make it readable only by you (<code>chmod 600</code> on the file) and keep it out of any
  folder you commit or sync.</li>
</ul>

<p>There is deliberately no command-line flag for the token: anything typed as an argument
lands in your shell history and is visible to other processes on the machine. Without a
token these commands stop before sending anything, with exit code 3.</p>

<h2 id="doctor">doctor — can this machine do it?</h2>

<pre>$ renest doctor                      # just this machine
$ renest doctor ./manifest.json      # this machine, against that nest
$ renest doctor --storage            # check the bucket settings too</pre>

<h2 id="verify">verify — prove what came back</h2>

<pre>$ renest verify ./manifest.json --dir ./run</pre>

<p><code>--check bytes</code> (the default) checks every file against its recorded fingerprint
and costs nothing. A failure names how many files are missing or wrong; <code>--json</code>
or <code>--report</code> lists which ones. <code>--check image</code> compares a picture rendered after rebuilding
against the one from packing time — pass it with <code>--rendered</code>, or add
<code>--render</code> to let Renest start the rebuilt app and render it for you (it asks
first: that uses this machine's GPU). <code>--check both</code> does both, and needs one of
those two flags for the same reason. <code>--report</code> writes the outcome to a file.</p>

<h2 id="rest">The other eight</h2>

<ul>
  <li><strong>watch</strong> — run your training command through it, and the nest
  records which machine libraries the run really loaded:
  <code>renest watch -- accelerate launch train.py</code>. A trainer exits when it is done,
  so by packing time there is nothing left to ask; this records it while the run is happening.
  It changes nothing about the run — same arguments, same output, same exit code.</li>
  <li><strong>lint</strong> — check a nest file for problems before you rely on it.</li>
  <li><strong>serve</strong> — run the local engine ComfyUI talks to (that's how the
  panel's "Nest this run" button reaches the tool). It listens on this machine only, on port
  7799 unless you pass <code>--port</code>; <code>--token-file</code> says where its token
  is kept.</li>
  <li><strong>presign</strong> — for nests in a bucket of your own: sign a restore code of
  time-limited links on the computer that holds the bucket key, so a rented machine never
  sees it. It needs that key configured (<code>renest doctor --storage</code> prints the
  steps) and stops without one. Codes for nests on your Renest drive come from the web
  console instead.
  <pre>$ renest presign --manifest ./nests/nests/&lt;nest-id&gt;/manifest.json --out code.json</pre>
  <code>--manifest</code> is the usual way in; <code>--nest ID</code> signs for a nest
  already in your bucket. <code>--expires-in SECONDS</code> sets how long the links last:
  6 hours by default, 24 hours at most.</li>
  <li><strong>update-rules</strong> — refresh the checks and compatibility data the tool
  uses.</li>
  <li><strong>list</strong> — list the nests on your Renest drive; add an id to see its versions.</li>
  <li><strong>export</strong> — take a complete copy of a nest off your drive, to this machine
  or on into your own bucket.</li>
  <li>Both <strong>list</strong> and <strong>export</strong> talk to your drive, so they need an
  access token — see <a href="#auth">Signing in to your drive</a>.</li>
  <li><strong>support</strong> — turn a failed run into something you can read, then paste
  into a ticket. It never goes online and never uploads.</li>
</ul>

<h2 id="flags">More flags, by command</h2>

<p>The flags above are the ones most people need. These are the next most useful; <code>renest
&lt;command&gt; --help</code> lists every one.</p>

<table>
  <thead><tr><th>Command</th><th>Flag</th><th>What it does</th></tr></thead>
  <tbody>
    <tr><td>pack</td><td><code>--comfyui-dir</code></td><td>The ComfyUI folder, when it isn't found under <code>--dir</code>.</td></tr>
    <tr><td>pack</td><td><code>--program-dir</code></td><td>Where ComfyUI's own program files are, when they are kept apart from your nodes and models (the ComfyUI desktop app does this).</td></tr>
    <tr><td>pack</td><td><code>--nest-id</code> / <code>--new-nest</code></td><td>Add this pack as a new version of the nest you name, or start a separate nest. By default a repeat pack of the same folder becomes a new version of the same nest.</td></tr>
    <tr><td>pack</td><td><code>--i-know</code></td><td>Pack even though something in your code folder looks like a credential. Handing the nest off still asks again.</td></tr>
    <tr><td>pack</td><td><code>--full-rehash</code></td><td>Read every file again, instead of only the ones whose size, time or place on disk moved since the last pack of this folder.</td></tr>
    <tr><td>pack</td><td><code>--no-licence-lookup</code></td><td>Don't look up licences; every licence stays marked as your own claim, unchecked.</td></tr>
    <tr><td>pack</td><td><code>--no-report</code></td><td>Don't report pack progress to your drive.</td></tr>
    <tr><td>restore</td><td><code>--blob-base URL</code></td><td>Where to download files from, when the nest lists no sources and you have no restore code.</td></tr>
    <tr><td>restore</td><td><code>--trust-unsafe-urls</code></td><td>Allow every unrecognised dependency source at once. For automation over your own nests; as a person, use <code>--trust-host</code>.</td></tr>
    <tr><td>doctor</td><td><code>--storage</code></td><td>Check your own bucket end to end, including where its key is kept.</td></tr>
    <tr><td>doctor</td><td><code>--lock FILE</code></td><td>Check that a lockfile's NVIDIA packages come from one CUDA release and that this driver is new enough for them.</td></tr>
    <tr><td>doctor</td><td><code>--no-skip-net</code></td><td>Also run the download speed test, which is skipped by default.</td></tr>
    <tr><td>verify</td><td><code>--yes</code></td><td>Answer yes to the rendering question up front, for unattended scripts.</td></tr>
    <tr><td>watch</td><td><code>--env-root</code></td><td>The folder that will be packed; the record is written inside it. Defaults to the current folder.</td></tr>
    <tr><td>lint</td><td><code>--blobs</code> / <code>--strict</code></td><td>Also check a local folder of stored files; treat warnings as failures.</td></tr>
    <tr><td>support</td><td><code>--dir</code> / <code>--run</code></td><td>The folder you were restoring into (required), and which run's records to read (default: the newest).</td></tr>
    <tr><td>list</td><td><code>NEST_ID</code></td><td>Show that nest's versions instead of all nests.</td></tr>
    <tr><td>export</td><td><code>--nest</code> / <code>--version</code> / <code>--out</code></td><td>Which nest and version to export (default: the latest fully checked one), and the local folder to write it to.</td></tr>
    <tr><td>export</td><td><code>--dest s3</code></td><td>Also push the exported copy into a bucket of your own.</td></tr>
  </tbody>
</table>

<h2 id="json">Machine-readable output</h2>

<p><code>--json</code> works before or after the subcommand, and comes in two shapes:</p>

<ul>
  <li><strong>doctor · lint · verify · presign · update-rules</strong> print <strong>one</strong> JSON document.</li>
  <li><strong>pack · restore</strong> print a stream of events, <strong>one JSON object per
  line</strong>, and the <strong>last line is always the final report</strong> — so a script
  can tail the progress and still get a single authoritative answer at the end.</li>
</ul>

<p>One exception today: <strong>restore</strong> prints its final report as a JSON document
on standard output even <em>without</em> <code>--json</code> (the progress narration you see
in a terminal goes to standard error). If you capture a restore's standard output, expect JSON either way.
The closing lines of a successful restore (<em>Done</em>, then <em>What's next</em>) go to standard
error <em>after</em> that report, so they are the last thing on your screen; standard output stays
pure JSON.</p>

<p><code>--verbose</code> sends debug logs to standard error, leaving standard output clean
for the JSON.</p>