<titledata-rh="true">The Drives CLI | Zrok</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://docs.zrok.io/docs/guides/drives/cli/"><metadata-rh="true"property="og:locale"content="en"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><metadata-rh="true"property="og:title"content="The Drives CLI | Zrok"><metadata-rh="true"name="description"content="The zrok drives CLI tools allow for simple, ergonomic management and synchronization of local and remote files."><metadata-rh="true"property="og:description"content="The zrok drives CLI tools allow for simple, ergonomic management and synchronization of local and remote files."><linkdata-rh="true"rel="icon"href="/img/space-ziggy.png"><linkdata-rh="true"rel="canonical"href="https://docs.zrok.io/docs/guides/drives/cli/"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/guides/drives/cli/"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/guides/drives/cli/"hreflang="x-default"><linkdata-rh="true"rel="preconnect"href="https://CO73R59OLO-dsn.algolia.net"crossorigin="anonymous"><linkrel="preconnect"href="https://www.googletagmanager.com">
<p>The zrok drives CLI tools allow for simple, ergonomic management and synchronization of local and remote files.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="sharing-a-drive">Sharing a Drive<ahref="#sharing-a-drive"class="hash-link"aria-label="Direct link to Sharing a Drive"title="Direct link to Sharing a Drive"></a></h2>
<p>Virtual drives are shared through the <code>zrok</code> CLI using the <code>--backend-mode drive</code> flag through the <code>zrok share</code> command, using either the <code>public</code> or <code>private</code> sharing modes. We'll use the <code>private</code> sharing mode for this example:</p>
<divclass="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ mkdir /tmp/junk</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok share private --headless --backend-mode drive /tmp/junk</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.124] INFO sdk-golang/ziti.(*listenerManager).createSessionWithBackoff: {session token=[cf640aac-2706-49ae-9cc9-9a497d67d9c5]} new service session</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.145] INFO main.(*sharePrivateCommand).run: allow other to access your share with the following command:</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">zrok access private wkcfb58vj51l</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>The command shown above creates an ephemeral, <code>private</code> drive share pointed at the local <code>/tmp/junk</code> folder.</p>
<p>Notice that the share token allocated by <code>zrok</code> is <code>wkcfb58vj51l</code>. We'll use that share token to identify our virtual drive in the following operations.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="working-with-a-private-drive-share">Working with a Private Drive Share<ahref="#working-with-a-private-drive-share"class="hash-link"aria-label="Direct link to Working with a Private Drive Share"title="Direct link to Working with a Private Drive Share"></a></h2>
<p>First, let's copy a file into our virtual drive using the <code>zrok copy</code> command:</p>
<p>We used the URL scheme <code>zrok://<shareToken></code> to refer to the private virtual drive we allocated above using the <code>zrok share private</code> command. Use <code>zrok://</code> URLs with the drives CLI tools to refer to contents of private virtual drives.</p>
<p>Next, let's get a directory listing of the virtual drive:</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="working-with-public-shares">Working with Public Shares<ahref="#working-with-public-shares"class="hash-link"aria-label="Direct link to Working with Public Shares"title="Direct link to Working with Public Shares"></a></h2>
<p>Public shares work very similarly to private shares, they just use a different URL scheme:</p>
<divclass="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok share public --headless --backend-mode drive /tmp/junk</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.708] INFO sdk-golang/ziti.(*listenerManager).createSessionWithBackoff: {session token=[05e0f48b-242b-4fd9-8edb-259488535c47]} new service session</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.878] INFO main.(*sharePublicCommand).run: access your zrok share at the following endpoints:</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> https://6kiww4bn7iok.share.zrok.io</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>The same commands, with a different URL scheme work with the <code>zrok</code> drives CLI:</p>
<p>For basic authentication provided by public shares, the <code>zrok</code> drives CLI offers the <code>--basic-auth</code> flag, which accepts a <code><username>:<password></code> parameter to specify the authentication for the public virtual drive (if it's required).</p>
<p>Alternatively, the authentication can be set using the <code>ZROK_DRIVES_BASIC_AUTH</code> environment variable:</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="one-way-synchronization">One-way Synchronization<ahref="#one-way-synchronization"class="hash-link"aria-label="Direct link to One-way Synchronization"title="Direct link to One-way Synchronization"></a></h2>
<p>The <code>zrok copy</code> command includes a <code>--sync</code> flag, which only copies files detected as <em>modified</em>. <code>zrok</code> considers a file with the same modification timestamp and size to be the same. Of course, this is not a strong guarantee that the files are equivalent. Future <code>zrok</code> drives versions will provide a cryptographically strong mechanism (a-la <code>rsync</code> and friends) to guarantee that files and trees of files are synchronized.</p>
<p>For now, the <code>--sync</code> flag provides a convenience mechanism to allow resuming copies of large file trees and provide a reasonable guarantee that the trees are in sync.</p>
<p>Let's take a look at <code>zrok copy --sync</code> in action:</p>
<divclass="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok copy --sync docs/ https://glmv049c62p7.share.zrok.io</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.636] INFO zrok/drives/sync.OneWay: => /_attic/</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.760] INFO zrok/drives/sync.OneWay: => /_attic/network/</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.816] INFO zrok/drives/sync.OneWay: => /_attic/network/_category_.json</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.928] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.987] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/ziti-ctrl.service</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.048] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/ziti-ctrl.yml</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.107] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/ziti-router0.service</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.167] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/ziti-router0.yml</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.218] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/zrok-access-public.service</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.273] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/zrok-ctrl.service</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.328] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/zrok-ctrl.yml</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.382] INFO zrok/drives/sync.OneWay: => /_attic/network/prod/zrok.io-network-skeleton.md</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.447] INFO zrok/drives/sync.OneWay: => /_attic/overview.md</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.572] INFO zrok/drives/sync.OneWay: => /_attic/sharing/</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.622] INFO zrok/drives/sync.OneWay: => /_attic/sharing/_category_.json</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.673] INFO zrok/drives/sync.OneWay: => /_attic/sharing/reserved_services.md</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.737] INFO zrok/drives/sync.OneWay: => /_attic/sharing/sharing_modes.md</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.793] INFO zrok/drives/sync.OneWay: => /_attic/v0.2_account_requests.md</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 1.902] INFO zrok/drives/sync.OneWay: => /_attic/v0.4_limits.md</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">...</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 9.691] INFO zrok/drives/sync.OneWay: => /images/zrok_web_ui_empty_shares.png</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 9.812] INFO zrok/dri
<p>Because the target drive was empty, <code>zrok copy --sync</code> copied the entire contents of the local <code>docs/</code> tree into the virtual drive. However, if we run that command again, we get:</p>
<p>Because we removed the <code>images/</code> tree from the virtual drive, <code>zrok copy --sync</code> detected this and copied the local <code>images/</code> tree back onto the virtual drive.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="drive-to-drive-copies-and-synchronization">Drive-to-Drive Copies and Synchronization<ahref="#drive-to-drive-copies-and-synchronization"class="hash-link"aria-label="Direct link to Drive-to-Drive Copies and Synchronization"title="Direct link to Drive-to-Drive Copies and Synchronization"></a></h2>
<p>The <code>zrok copy</code> CLI can operate on pairs of virtual drives remotely, without ever having to store files locally. This allow for drive-to-drive copies and synchronization.</p>
<p>Specifying the same URL for both the source and the target of a <code>--sync</code> operation should always result in nothing being copied... they are the same drive with the same state.</p>
<p>We can copy files between two virtual drives with a single command:</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="copying-from-drives-to-the-local-filesystem">Copying from Drives to the Local Filesystem<ahref="#copying-from-drives-to-the-local-filesystem"class="hash-link"aria-label="Direct link to Copying from Drives to the Local Filesystem"title="Direct link to Copying from Drives to the Local Filesystem"></a></h2>
<p>In the current version of the drives CLI, <code>zrok copy</code> always assumes the destination is a directory. There is currently no way to do:</p>
<p>It's in the backlog to support file destinations in a future release of <code>zrok</code>. So, when using <code>zrok copy</code>, always take note of the destination.</p>
<p><code>zrok copy</code> supports a default destination of <code>file://.</code>, so you can do single parameter <code>zrok copy</code> commands like this:</p>
<divclass="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok ls https://azc47r3cwjds.share.zrok.io</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">┌──────┬─────────┬─────────┬───────────────────────────────┐</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">│ TYPE │ NAME │ SIZE │ MODIFIED │</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">├──────┼─────────┼─────────┼───────────────────────────────┤</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">│ │ LICENSE │ 11.3 kB │ 2023-07-21 13:17:56 -0400 EDT │</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">└──────┴─────────┴─────────┴───────────────────────────────┘</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok copy https://azc47r3cwjds.share.zrok.io/LICENSE</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.260] INFO zrok/drives/sync.OneWay: => /LICENSE</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">copy complete!</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ ls -l</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">total 12</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">-rw-rw-r-- 1 michael michael 11346 Jan 19 13:29 LICENSE</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>You can also specify a local folder as the destination for your copy:</p>
<divclass="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok copy https://azc47r3cwjds.share.zrok.io/LICENSE /tmp/inbox</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.221] INFO zrok/drives/sync.OneWay: => /LICENSE</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">copy complete! </span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ l /tmp/inbox</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">total 12</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">-rw-rw-r-- 1 michael michael 11346 Jan 19 13:30 LICENSE</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="unique-names-and-reserved-shares">Unique Names and Reserved Shares<ahref="#unique-names-and-reserved-shares"class="hash-link"aria-label="Direct link to Unique Names and Reserved Shares"title="Direct link to Unique Names and Reserved Shares"></a></h2>
<p>Private reserved shares with unque names can be particularly useful with the drives CLI:</p>
<divclass="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok reserve private -b drive --unique-name mydrive /tmp/junk</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.315] INFO main.(*reserveCommand).run: your reserved share token is 'mydrive'</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok share reserved --headless mydrive</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.289] INFO main.(*shareReservedCommand).run: sharing target: '/tmp/junk'</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.289] INFO main.(*shareReservedCommand).run: using existing backend proxy endpoint: /tmp/junk</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.767] INFO sdk-golang/ziti.(*listenerManager).createSessionWithBackoff: {session token=[d519a436-9fb5-4207-afd5-7cbc28fb779a]} new service session</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.927] INFO main.(*shareReservedCommand).run: use this command to access your zrok share: 'zrok access private mydrive'</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>This makes working with <code>zrok://</code> URLs particularly convenient:</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="future-enhancements">Future Enhancements<ahref="#future-enhancements"class="hash-link"aria-label="Direct link to Future Enhancements"title="Direct link to Future Enhancements"></a></h2>
<p>Coming in a future release of <code>zrok</code> drives are features like:</p>
<ul>
<li>two-way synchronization between multiple hosts... allowing for shared "dropbox-like" usage scenarios between multiple environments</li>
<li>better ergonomics for single-file destinations</li>
