Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 36 additions & 2 deletions site/guide.html
Original file line number Diff line number Diff line change
Expand Up @@ -149,10 +149,11 @@ <h3>pfm totp NAME <span class="what">2FA code</span></h3>
</article>
<article class="cmd">
<h3>pfm codes NAME <span class="what">recovery code</span></h3>
<p>Copies the next unused code and marks it used. Warns when two or fewer are left. With <code>--list</code>, shows them all and which were used (on screen, in plain text). To add the codes, see <a href="#codes">recovery codes</a>.</p>
<p>Copies the next unused code and marks it used. Warns when two or fewer are left. With <code>--list</code>, shows them all and which were used (on screen, in plain text). With <code>--stdout</code>, prints the code alone instead of copying it, for programs (see <a href="#writable-agent">Agent</a>). To add the codes, see <a href="#codes">recovery codes</a>.</p>
<div class="ex">
<div class="line"><span class="c">pfm codes openai <span class="hash"># copies the next one and marks it used</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">pfm codes openai --list <span class="hash"># all of them, (used) on the used ones</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">pfm codes openai --stdout <span class="hash"># the code alone, not copied</span></span><button type="button">Copy</button></div>
</div>
<p class="note">A code cannot be unmarked: run <code>pfm codes</code> only when you are about to use one. Marking on copy errs on the safe side: at worst you are one code short, and a spent code never comes back to the list. To rebuild the list, paste the codes again with <code>pfm edit NAME --codes</code>.</p>
</article>
Expand Down Expand Up @@ -466,7 +467,7 @@ <h3>pfm passwd <span class="what">change the master phrase</span></h3>

<section id="agent">
<h2>Agent (programs)</h2>
<p class="sub">Programs (scripts, AI agents) don't use the session. They only read the items you mark, and nothing else in the vault.</p>
<p class="sub">Programs (scripts, AI agents) don't use the session. They only read the items you mark, and nothing else in the vault. If you allow it, they also keep the items they create themselves.</p>
<div class="cards">
<article class="cmd">
<div class="tbl"><table>
Expand All @@ -487,6 +488,39 @@ <h2>Agent (programs)</h2>
</div>
<p class="note">With no agent released, <code>get --stdout</code> outside a terminal fails at once, instead of waiting for a phrase nobody will type.</p>
</article>
<article class="cmd" id="writable-agent">
<h3>pfm unlock --writable <span class="what">programs that keep what they create</span></h3>
<p>With <code>--writable</code>, a program can also store items in the vault, without the master phrase: an AI agent that creates test accounts in an application you authorized it to test keeps the password, the 2FA secret and the recovery codes there, and reads them back later. A program changes only the items programs created. Yours it still only reads, and only the ones marked <code>--agent</code>.</p>
<div class="tbl"><table>
<tr><th>Command</th><th>What it does</th></tr>
<tr><td><code>pfm unlock --writable</code></td><td>you, in a terminal: releases reading and writing for 8 hours (takes <code>--for</code> and item names, as always)</td></tr>
<tr><td><code>pfm add NAME --agent-space</code></td><td>the program creates an item; takes <code>--username</code>, <code>--url</code>, <code>--generate</code> and <code>--kind</code></td></tr>
<tr><td><code>pfm edit NAME --agent-space</code></td><td>the program changes an item programs created; the options of <code>edit</code>, except attachments and <code>--agent</code></td></tr>
<tr><td><code>pfm get NAME --stdout</code></td><td>reads a value; with <code>--field totp</code>, the current 2FA code</td></tr>
<tr><td><code>pfm codes NAME --stdout</code></td><td>prints the next recovery code and marks it used</td></tr>
<tr><td><code>pfm list --agent-space</code></td><td>what the agent holds, without secrets</td></tr>
</table></div>
<div class="ex">
<div class="line"><span class="c">pfm unlock --for 8h --writable <span class="hash"># you, once, with the master phrase</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">pfm add "acme test admin" --agent-space --username admin@example.com --url https://staging.example.com --generate <span class="hash"># the program: an account with a generated password</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">echo "$PASSWORD" | pfm add "acme test user" --agent-space --username you@example.com <span class="hash"># a password the program already has, on stdin</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">pfm get "acme test admin" --stdout <span class="hash"># reads the password back</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">echo "$TOTP_SECRET" | pfm edit "acme test user" --agent-space --totp <span class="hash"># keeps the 2FA secret</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">pfm get "acme test user" --field totp --stdout <span class="hash"># the 2FA code right now</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">printf '%s\n' "$CODE_1" "$CODE_2" | pfm edit "acme test user" --agent-space --codes <span class="hash"># keeps the codes, one per line</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">pfm codes "acme test user" --stdout <span class="hash"># uses one code</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">pfm list --agent-space <span class="hash"># what the agent holds</span></span><button type="button">Copy</button></div>
<div class="line"><span class="c">pfm status <span class="hash"># shows whether the agent takes writes and how many changes wait</span></span><button type="button">Copy</button></div>
</div>
<p>Each secret comes in on a line of stdin, never as an argument. What the program writes stays encrypted on the laptop, and <strong>your next command</strong> in a terminal (any of them: <code>pfm list</code>, <code>pfm get</code>…) brings those items into the vault and syncs. In <code>pfm list</code> they show as <code>agent-made</code> in the AGENT column.</p>
<ul>
<li><strong>Your items stay out of reach</strong>: <code>edit --agent-space</code> and <code>codes --stdout</code> refuse an item you created, marked or not.</li>
<li><strong>An item of yours always wins a search</strong>: if a program creates an item called <code>router</code>, <code>pfm get router</code> still finds your <code>OpenRouter</code>.</li>
<li><strong>Deleting is yours</strong>: programs neither delete nor attach files. Use <code>pfm rm NAME</code>.</li>
<li><strong>Limits</strong>: up to 200 items created by programs, of up to 64 KiB each.</li>
</ul>
<p class="note">After a reboot or a <code>pfm lock</code>, what was written is not lost: it enters the vault with your next command. The program reads and writes again only after a new <code>pfm unlock --writable</code>. Treat what a program stored as coming from outside: it may have been written by the application it was testing.</p>
</article>
</div>
</section>

Expand Down
38 changes: 36 additions & 2 deletions site/pt-br/guide.html
Original file line number Diff line number Diff line change
Expand Up @@ -148,10 +148,11 @@ <h3>pfm totp NOME <span class="what">código 2FA</span></h3>
</article>
<article class="cmd">
<h3>pfm codes NOME <span class="what">código de recuperação</span></h3>
<p>Copia o próximo código ainda não usado e o marca como usado. Avisa quando restam dois ou menos. Com <code>--list</code>, mostra todos e quais já foram usados (na tela, em texto puro). Para cadastrar os códigos, ver <a href="#codigos">códigos de recuperação</a>.</p>
<p>Copia o próximo código ainda não usado e o marca como usado. Avisa quando restam dois ou menos. Com <code>--list</code>, mostra todos e quais já foram usados (na tela, em texto puro). Com <code>--stdout</code>, imprime o código sozinho em vez de copiar, para programas (ver <a href="#agente-gravavel">Agente</a>). Para cadastrar os códigos, ver <a href="#codigos">códigos de recuperação</a>.</p>
<div class="ex">
<div class="line"><span class="c">pfm codes openai <span class="hash"># copia o próximo e marca como usado</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">pfm codes openai --list <span class="hash"># todos, com (used) nos usados</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">pfm codes openai --stdout <span class="hash"># o código sozinho, sem copiar</span></span><button type="button">Copiar</button></div>
</div>
<p class="note">Não há como desmarcar um código: rode <code>pfm codes</code> só na hora de usar. Marcar ao copiar é o lado seguro do erro: no pior caso sobra um código a menos, e nunca um já gasto volta para a lista. Se precisar refazer a lista, cole os códigos de novo com <code>pfm edit NOME --codes</code>.</p>
</article>
Expand Down Expand Up @@ -465,7 +466,7 @@ <h3>pfm passwd <span class="what">trocar a frase mestra</span></h3>

<section id="agente">
<h2>Agente (programas)</h2>
<p class="sub">Programas (scripts, agentes de IA) não usam a sessão. Eles só leem os itens que você marcar, e nada mais do cofre.</p>
<p class="sub">Programas (scripts, agentes de IA) não usam a sessão. Eles só leem os itens que você marcar, e nada mais do cofre. Se você liberar, também guardam os itens que eles mesmos criam.</p>
<div class="cards">
<article class="cmd">
<div class="tbl"><table>
Expand All @@ -486,6 +487,39 @@ <h2>Agente (programas)</h2>
</div>
<p class="note">Sem agente liberado, o <code>get --stdout</code> fora de um terminal falha na hora, em vez de ficar esperando uma frase que ninguém vai digitar.</p>
</article>
<article class="cmd" id="agente-gravavel">
<h3>pfm unlock --writable <span class="what">programas que guardam o que criam</span></h3>
<p>Com <code>--writable</code>, um programa também pode guardar itens no cofre, sem a frase mestra: um agente de IA que cria contas de teste numa aplicação que você o autorizou a testar guarda ali a senha, o segredo do 2FA e os códigos de recuperação, e os lê de volta depois. O programa só altera os itens que programas criaram. Os seus ele continua só lendo, e apenas os marcados com <code>--agent</code>.</p>
<div class="tbl"><table>
<tr><th>Comando</th><th>O que faz</th></tr>
<tr><td><code>pfm unlock --writable</code></td><td>você, no terminal: libera a leitura e a escrita por 8 horas (aceita <code>--for</code> e nomes de itens, como sempre)</td></tr>
<tr><td><code>pfm add NOME --agent-space</code></td><td>o programa cria um item; aceita <code>--username</code>, <code>--url</code>, <code>--generate</code> e <code>--kind</code></td></tr>
<tr><td><code>pfm edit NOME --agent-space</code></td><td>o programa altera um item que programas criaram; as opções do <code>edit</code>, menos anexos e <code>--agent</code></td></tr>
<tr><td><code>pfm get NOME --stdout</code></td><td>lê um valor; com <code>--field totp</code>, o código 2FA do momento</td></tr>
<tr><td><code>pfm codes NOME --stdout</code></td><td>imprime o próximo código de recuperação e o marca como usado</td></tr>
<tr><td><code>pfm list --agent-space</code></td><td>o que o agente guarda, sem segredos</td></tr>
</table></div>
<div class="ex">
<div class="line"><span class="c">pfm unlock --for 8h --writable <span class="hash"># você, uma vez, com a frase mestra</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">pfm add "acme teste admin" --agent-space --username admin@exemplo.com --url https://staging.exemplo.com --generate <span class="hash"># o programa: conta com senha gerada</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">echo "$SENHA" | pfm add "acme teste usuario" --agent-space --username voce@exemplo.com <span class="hash"># senha que o programa já tem, pelo stdin</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">pfm get "acme teste admin" --stdout <span class="hash"># lê a senha de volta</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">echo "$SEGREDO_2FA" | pfm edit "acme teste usuario" --agent-space --totp <span class="hash"># guarda o segredo do 2FA</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">pfm get "acme teste usuario" --field totp --stdout <span class="hash"># o código 2FA de agora</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">printf '%s\n' "$CODIGO_1" "$CODIGO_2" | pfm edit "acme teste usuario" --agent-space --codes <span class="hash"># guarda os códigos, um por linha</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">pfm codes "acme teste usuario" --stdout <span class="hash"># gasta um código</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">pfm list --agent-space <span class="hash"># o que o agente guarda</span></span><button type="button">Copiar</button></div>
<div class="line"><span class="c">pfm status <span class="hash"># mostra se o agente aceita escrita e quantas mudanças esperam</span></span><button type="button">Copiar</button></div>
</div>
<p>Cada segredo entra por uma linha do stdin, nunca como argumento. O que o programa grava fica cifrado no notebook, e o <strong>seu próximo comando</strong> no terminal (qualquer um: <code>pfm list</code>, <code>pfm get</code>…) traz esses itens para o cofre e sincroniza. No <code>pfm list</code> eles aparecem como <code>agent-made</code> na coluna AGENT.</p>
<ul>
<li><strong>Os seus itens ficam fora do alcance</strong>: <code>edit --agent-space</code> e <code>codes --stdout</code> recusam um item que você criou, marcado ou não.</li>
<li><strong>Um item seu sempre ganha a busca</strong>: se um programa criar um item chamado <code>router</code>, <code>pfm get router</code> continua achando o seu <code>OpenRouter</code>.</li>
<li><strong>Apagar é com você</strong>: programas não apagam nem anexam arquivos. Use <code>pfm rm NOME</code>.</li>
<li><strong>Limites</strong>: até 200 itens criados por programas, de até 64 KiB cada.</li>
</ul>
<p class="note">Depois de reiniciar o computador ou de um <code>pfm lock</code>, o que foi gravado não se perde: entra no cofre no seu próximo comando. O programa só volta a ler e gravar depois de um novo <code>pfm unlock --writable</code>. Trate o que um programa guardou como vindo de fora: pode ter sido escrito pela aplicação que ele estava testando.</p>
</article>
</div>
</section>

Expand Down
Loading
Loading