https://pockethost.io/_app/immutable/chunks/sisk7D7O.js

1import{B as e,Ct as t,M as n,R as r,St as i,kt as a,ot as o,st as s}from"./CzsObDY8.js";import"./xihTtKlq.js";import"./C5qy-xbg.js";var c=a({default:()=>p,metadata:()=>l}),l={title:`phio CLI`,description:`Install and use the phio CLI to link, watch, deploy, browse files, and tail logs for PocketHost instances over SFTP`},{title:u,description:d}=l,f=e(`<h1>phio CLI</h1> <p><strong>phio</strong> is the PocketHost command-line tool for syncing local PocketBase project files to your instance and tailing instance logs.</p> <p>Deploy and watch mode use <strong>SFTP on port 2222</strong> with an Ed25519 deploy key. phio creates and registers that key for you on first use.</p> <h2>Install</h2> <p>Requires <strong>Node.js 24+</strong>.</p> <pre class="hljs language-bash"></pre> <p>From the PocketHost monorepo during development:</p> <pre class="hljs language-bash"></pre> <h2>Quick start</h2> <pre class="hljs language-bash"></pre> <ol><li><strong><code>phio login</code></strong> — sign in with your PocketHost email and password.</li> <li><strong><code>phio link &lt;instance&gt;</code></strong> — save the default instance to <code>.phioconfig</code> in the current directory.</li> <li><strong><code>phio dev</code></strong> — watch local changes and sync them to the remote instance.</li></ol> <p>For a one-shot upload without watching:</p> <pre class="hljs language-bash"></pre> <p>Pass an instance name on any command to override the linked default:</p> <pre class="hljs language-bash"></pre> <h2>Commands</h2> <table><thead><tr><th>Command</th><th>Purpose</th></tr></thead><tbody><tr><td><code>phio login</code></td><td>Sign in to PocketHost</td></tr><tr><td><code>phio logout</code></td><td>Clear saved session</td></tr><tr><td><code>phio info</code> (<code>whoami</code>)</td><td>Show login, linked instance, and deploy key status</td></tr><tr><td><code>phio list</code></td><td>List instances on your account</td></tr><tr><td><code>phio link [instance]</code></td><td>Link this directory to an instance (writes <code>.phioconfig</code>)</td></tr><tr><td><code>phio dev [instance]</code></td><td>Watch local files and sync on change</td></tr><tr><td><code>phio deploy [instance]</code></td><td>One-shot sync to remote</td></tr><tr><td><code>phio sftp [instance]</code></td><td>Interactive SFTP session to instance files</td></tr><tr><td><code>phio logs [instance]</code></td><td>Tail instance logs over SSE</td></tr></tbody></table> <p><code>dev</code> and <code>deploy</code> accept:</p> <ul><li><code>-v, --verbose</code> — verbose sync output</li> <li><code>-i, --include &lt;patterns...&gt;</code> — extra include globs (comma-separated values work)</li> <li><code>-e, --exclude &lt;patterns...&gt;</code> — extra exclude globs</li></ul> <p>Default <strong>includes</strong>: <code>pb_*</code>, <code>package.json</code>, <code>bun.lock</code>, <code>bun.lockb</code>, <code>patches/**</code>.</p> <p>Default <strong>excludes</strong>: <code>pb_data/**</code>.</p> <p><code>phio sftp</code> accepts:</p> <ul><li><code>--print</code> — print the underlying <code>sftp</code> command instead of running it (useful when OpenSSH client tools are not installed)</li></ul> <h2>Interactive SFTP (<code>phio sftp</code>)</h2> <p>Browse and edit instance files in an interactive SFTP session. phio uses the same <strong><code>Phio</code></strong> deploy key as <code>dev</code> and <code>deploy</code>.</p> <pre class="hljs language-bash"></pre> <p>When a project is linked, phio opens your instance directory (<code>&#123;subdomain&#125;/</code>). With no linked instance, phio connects at the SFTP root so you can <code>cd</code> into any instance you have access to.</p> <p>phio runs your system’s <strong><code>sftp</code></strong> client when it is on <code>PATH</code> (OpenSSH on macOS/Linux, optional Windows OpenSSH). If <code>sftp</code> is missing, phio prints the full command to run manually. See <strong><a href="/docs/ftp">SFTP File Access</a></strong> for client setup on every platform.</p> <p>This is file access only (<code>ls</code>, <code>cd</code>, <code>get</code>, <code>put</code>, and the rest). There is no remote shell or <code>exec</code>.</p> <h2>Linking an instance (<code>.phioconfig</code>)</h2> <p><code>phio link</code> writes a <code>.phioconfig</code> file in your project root:</p> <pre class="hljs language-json"></pre> <p>Commit this file so teammates and CI know which instance the project deploys to.</p> <h3>Legacy config migration</h3> <p>

1Older projects may still have:</p> <ul><li><code>"pockethost": &#123; "instanceName": "..." &#125;</code> in <code>package.json</code>, or</li> <li>a standalone <code>pockethost.json</code></li></ul> <p>phio migrates those to <code>.phioconfig</code> automatically the first time it reads them. Legacy entries are removed from <code>package.json</code>, and <code>pockethost.json</code> is deleted after migration.</p> <h2>Deploy key (SFTP auth)</h2> <p>phio does not use your PocketHost password for file sync. On <code>login</code>, <code>info</code>, and before each <code>dev</code>, <code>deploy</code>, or <code>sftp</code>, phio:</p> <ol><li>Generates or loads an Ed25519 keypair under your phio config directory (default <code>~/.config/phio/</code>): <ul><li><code>phio_deploy_ed25519</code> (private key)</li> <li><code>phio_deploy_ed25519.pub</code> (public key)</li></ul></li> <li>Ensures <strong><a href="/account/keys">Account → Keys</a></strong> has a key labeled <strong><code>Phio</code></strong> whose public key matches the local <code>.pub</code>.</li> <li>Creates the remote key on first run with access to <strong>all instances</strong> on your account.</li></ol> <p>Run <code>phio info</code> to inspect deploy key paths, fingerprint, and remote registration status.</p> <p>If the remote <strong><code>Phio</code></strong> key does not match your local key, delete the local key files to regenerate, or update the key in the dashboard. See <strong><a href="/blog/account-access-keys">Account access keys</a></strong> for scoped keys in CI.</p> <h2>How sync works</h2> <p>phio connects to:</p> <table><thead><tr><th>Setting</th><th>Value</th></tr></thead><tbody><tr><td>Host</td><td><code>ftp.pockethost.io</code></td></tr><tr><td>Port</td><td><code>2222</code></td></tr><tr><td>Protocol</td><td>SFTP</td></tr><tr><td>Username</td><td>Your PocketHost email</td></tr><tr><td>Auth</td><td>Local <strong><code>Phio</code></strong> deploy key</td></tr><tr><td>Remote directory</td><td><code>&#123;instanceName&#125;/</code> (instance root)</td></tr></tbody></table> <p>Sync is incremental. phio writes <code>.ftp-deploy-sync-state.json</code> at the instance root to track what changed. Do not delete that file unless you want a full resync.</p> <p>Use <strong><code>phio sftp</code></strong> for an interactive session with the same credentials, or see <strong><a href="/docs/ftp">SFTP File Access</a></strong> for Cyberduck, FileZilla, VS Code extensions, and manual <code>sftp</code> setup.</p> <h2>Environment variables</h2> <p>Override saved config without editing files:</p> <table><thead><tr><th>Variable</th><th>Purpose</th></tr></thead><tbody><tr><td><code>PHIO_USERNAME</code></td><td>PocketHost email (non-interactive login)</td></tr><tr><td><code>PHIO_PASSWORD</code></td><td>PocketHost password (with <code>PHIO_USERNAME</code>)</td></tr><tr><td><code>PHIO_INSTANCE_NAME</code></td><td>Default instance name</td></tr><tr><td><code>PHIO_MOTHERSHIP_URL</code></td><td>Mothership API URL (default production)</td></tr><tr><td><code>PHIO_HOME</code></td><td>phio config directory (default OS config path for <code>phio</code>)</td></tr></tbody></table> <p><code>PHIO_INSTANCE_NAME</code> takes precedence over <code>.phioconfig</code>.</p> <h2>CI example</h2> <p>Use env-based login and a linked instance name in CI:</p> <pre class="hljs language-yaml"></pre> <p>Store your PocketHost email and password as repository secrets. phio registers its deploy key on first deploy.</p> <p>For GitHub Actions that already use <a href="https://github.com/SamKirkland/FTP-Deploy-Action" rel="nofollow">SamKirkland/FTP-Deploy-Action</a>, migrate from FTPS on port 21 to SFTP on port 2222 with an Ed25519 private key. See <strong><a href="/blog/ftps-sunset">FTPS sunset</a></strong> for the timeline.</p> <h2>Troubleshooting</h2> <h3><code>No instance name provided and none was found in .phioconfig</code></h3> <p>Run <code>phio link &lt;instance&gt;</code> in your project directory, or pass the instance name on the command line.</p> <h3>Deploy key mismatch</h3> <p>The <strong><code>Phio</code></strong> key in <strong><a href="/account/keys">Account → Keys</a></strong> must match <code>~/.config/phio/phio_deploy_ed25519.pub</code>. Delete the local key files and run <code>phio info</code> or <code>phio deploy</code> to regenerate and re-register.</p> <h3>Permission denied (publickey) during deploy</h3> <p>Confirm you are logged in (<code>phio login</code> or <code>PHIO_USERNAME</code>/<code>PHIO_PASSWORD</code>), then run <code>phio info</code> to verify the deploy key is registered.</p> <h3><code>Could not find 'sftp' on PATH</code></h3> <p>Install OpenSSH client tools for your OS, or run <code>phio sftp --print</code> and paste the command into your preferred SFTP client. See <strong><a href="/docs/ftp">SFTP File Access</a></strong>.</p> <h3>Session expired</h3> <p>Run <code>phio login</code> again, or set <code>PHIO_USERNAME</code> and <code>PHIO_PASSWORD</code> for non-interactive environments.</p>`,1);function p(e){var a=f(),c=s(o(a),10);n(c,()=>`<code class="hljs language-bash">npm install -g phio</code>`,!0),t(c);var l=s(c,4);n(l,()=>`<code class="hljs language-bash">pnpm dev:phio -- --<span class="hljs-built_in">help</span></code>`,!0),t(l);var u=s(l,4);n(u,()=>`<code class="hljs language-bash">phio login
2phio <span class="hljs-built_in">link</span> my-instance
3phio dev</code>`,!0),t(u);var d=s(u,6);n(d,()=>`<code class="hljs language-bash">phio deploy</code>`,!0),t(d);var p=s(d,4);n(p,()=>`<code class="hljs language-bash">phio deploy staging
4phio logs my-instance</code>`,!0),t(p);var m=s(p,22);n(m,()=>`<code class="hljs language-bash">

4phio sftp              <span class="hljs-comment"># linked instance from .phioconfig</span>
5phio sftp my-instance  <span class="hljs-comment"># explicit instance</span>
6phio sftp --<span class="hljs-built_in">print</span>      <span class="hljs-comment"># show the sftp command without running it</span></code>`,!0),t(m);var h=s(m,12);n(h,()=>`<code class="hljs language-json"><span class="hljs-punctuation">&#123;</span>
7  <span class="hljs-attr">&quot;instanceName&quot;</span><span class="hljs-punctuation">:</span> <span class="hljs-string">&quot;all-your-base&quot;</span>
8<span class="hljs-punctuation">&#125;</span></code>`,!0),t(h);var g=s(h,44);n(g,()=>`<code class="hljs language-yaml"><span class="hljs-attr">on:</span>
9  <span class="hljs-attr">push:</span>
10    <span class="hljs-attr">branches:</span> [<span class="hljs-string">main</span>]
11
12<span class="hljs-attr">jobs:</span>
13  <span class="hljs-attr">deploy:</span>
14    <span class="hljs-attr">runs-on:</span> <span class="hljs-string">ubuntu-latest</span>
15    <span class="hljs-attr">steps:</span>
16      <span class="hljs-bullet">-</span> <span class="hljs-attr">uses:</span> <span class="hljs-string">actions/checkout@v4</span>
17
18      <span class="hljs-bullet">-</span> <span class="hljs-attr">uses:</span> <span class="hljs-string">actions/setup-node@v4</span>
19        <span class="hljs-attr">with:</span>
20          <span class="hljs-attr">node-version:</span> <span class="hljs-string">&#x27;24&#x27;</span>
21
22      <span class="hljs-bullet">-</span> <span class="hljs-attr">name:</span> <span class="hljs-string">Deploy</span> <span class="hljs-string">to</span> <span class="hljs-string">PocketHost</span>
23        <span class="hljs-attr">env:</span>
24          <span class="hljs-attr">PHIO_USERNAME:</span> <span class="hljs-string">$&#123;&#123;</span> <span class="hljs-string">secrets.POCKETHOST_EMAIL</span> <span class="hljs-string">&#125;&#125;</span>
25          <span class="hljs-attr">PHIO_PASSWORD:</span> <span class="hljs-string">$&#123;&#123;</span> <span class="hljs-string">secrets.POCKETHOST_PASSWORD</span> <span class="hljs-string">&#125;&#125;</span>
26          <span class="hljs-attr">PHIO_INSTANCE_NAME:</span> <span class="hljs-string">my-instance</span>
27        <span class="hljs-attr">run:</span> <span class="hljs-string">|
28          npm install -g phio
29          phio deploy -v</span></code>`,!0),t(g),i(26),r(e,a)}export{p as n,c as t};