From 42d0ec0dad878fa0193b7c5783d7cd039dadfc99 Mon Sep 17 00:00:00 2001 From: Eduardo Doege Date: Wed, 11 Nov 2026 10:57:30 -0300 Subject: [PATCH] feat(site): document the writable agent and codes --stdout in the guide Follows passforme's unlock --writable: programs keep what they create with add, edit and list --agent-space, read it back with get --stdout and use recovery codes with codes --stdout. Both languages, with the examples tried in a throwaway vault. --- site/guide.html | 38 ++++++++++++++++++++-- site/pt-br/guide.html | 38 ++++++++++++++++++++-- src/guide.html | 76 ++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 144 insertions(+), 8 deletions(-) diff --git a/site/guide.html b/site/guide.html index fb0c9d7..5f9fc15 100644 --- a/site/guide.html +++ b/site/guide.html @@ -149,10 +149,11 @@

pfm totp NAME 2FA code

pfm codes NAME recovery code

-

Copies the next unused code and marks it used. Warns when two or fewer are left. With --list, shows them all and which were used (on screen, in plain text). To add the codes, see recovery codes.

+

Copies the next unused code and marks it used. Warns when two or fewer are left. With --list, shows them all and which were used (on screen, in plain text). With --stdout, prints the code alone instead of copying it, for programs (see Agent). To add the codes, see recovery codes.

pfm codes openai # copies the next one and marks it used
pfm codes openai --list # all of them, (used) on the used ones
+
pfm codes openai --stdout # the code alone, not copied

A code cannot be unmarked: run pfm codes 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 pfm edit NAME --codes.

@@ -466,7 +467,7 @@

pfm passwd change the master phrase

Agent (programs)

-

Programs (scripts, AI agents) don't use the session. They only read the items you mark, and nothing else in the vault.

+

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.

@@ -487,6 +488,39 @@

Agent (programs)

With no agent released, get --stdout outside a terminal fails at once, instead of waiting for a phrase nobody will type.

+
+

pfm unlock --writable programs that keep what they create

+

With --writable, 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 --agent.

+
+ + + + + + + +
CommandWhat it does
pfm unlock --writableyou, in a terminal: releases reading and writing for 8 hours (takes --for and item names, as always)
pfm add NAME --agent-spacethe program creates an item; takes --username, --url, --generate and --kind
pfm edit NAME --agent-spacethe program changes an item programs created; the options of edit, except attachments and --agent
pfm get NAME --stdoutreads a value; with --field totp, the current 2FA code
pfm codes NAME --stdoutprints the next recovery code and marks it used
pfm list --agent-spacewhat the agent holds, without secrets
+
+
pfm unlock --for 8h --writable # you, once, with the master phrase
+
pfm add "acme test admin" --agent-space --username admin@example.com --url https://staging.example.com --generate # the program: an account with a generated password
+
echo "$PASSWORD" | pfm add "acme test user" --agent-space --username you@example.com # a password the program already has, on stdin
+
pfm get "acme test admin" --stdout # reads the password back
+
echo "$TOTP_SECRET" | pfm edit "acme test user" --agent-space --totp # keeps the 2FA secret
+
pfm get "acme test user" --field totp --stdout # the 2FA code right now
+
printf '%s\n' "$CODE_1" "$CODE_2" | pfm edit "acme test user" --agent-space --codes # keeps the codes, one per line
+
pfm codes "acme test user" --stdout # uses one code
+
pfm list --agent-space # what the agent holds
+
pfm status # shows whether the agent takes writes and how many changes wait
+
+

Each secret comes in on a line of stdin, never as an argument. What the program writes stays encrypted on the laptop, and your next command in a terminal (any of them: pfm list, pfm get…) brings those items into the vault and syncs. In pfm list they show as agent-made in the AGENT column.

+
    +
  • Your items stay out of reach: edit --agent-space and codes --stdout refuse an item you created, marked or not.
  • +
  • An item of yours always wins a search: if a program creates an item called router, pfm get router still finds your OpenRouter.
  • +
  • Deleting is yours: programs neither delete nor attach files. Use pfm rm NAME.
  • +
  • Limits: up to 200 items created by programs, of up to 64 KiB each.
  • +
+

After a reboot or a pfm lock, what was written is not lost: it enters the vault with your next command. The program reads and writes again only after a new pfm unlock --writable. Treat what a program stored as coming from outside: it may have been written by the application it was testing.

+
diff --git a/site/pt-br/guide.html b/site/pt-br/guide.html index 5ebb607..dea07e0 100644 --- a/site/pt-br/guide.html +++ b/site/pt-br/guide.html @@ -148,10 +148,11 @@

pfm totp NOME código 2FA

pfm codes NOME código de recuperação

-

Copia o próximo código ainda não usado e o marca como usado. Avisa quando restam dois ou menos. Com --list, mostra todos e quais já foram usados (na tela, em texto puro). Para cadastrar os códigos, ver códigos de recuperação.

+

Copia o próximo código ainda não usado e o marca como usado. Avisa quando restam dois ou menos. Com --list, mostra todos e quais já foram usados (na tela, em texto puro). Com --stdout, imprime o código sozinho em vez de copiar, para programas (ver Agente). Para cadastrar os códigos, ver códigos de recuperação.

pfm codes openai # copia o próximo e marca como usado
pfm codes openai --list # todos, com (used) nos usados
+
pfm codes openai --stdout # o código sozinho, sem copiar

Não há como desmarcar um código: rode pfm codes 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 pfm edit NOME --codes.

@@ -465,7 +466,7 @@

pfm passwd trocar a frase mestra

Agente (programas)

-

Programas (scripts, agentes de IA) não usam a sessão. Eles só leem os itens que você marcar, e nada mais do cofre.

+

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.

@@ -486,6 +487,39 @@

Agente (programas)

Sem agente liberado, o get --stdout fora de um terminal falha na hora, em vez de ficar esperando uma frase que ninguém vai digitar.

+
+

pfm unlock --writable programas que guardam o que criam

+

Com --writable, 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 --agent.

+
+ + + + + + + +
ComandoO que faz
pfm unlock --writablevocê, no terminal: libera a leitura e a escrita por 8 horas (aceita --for e nomes de itens, como sempre)
pfm add NOME --agent-spaceo programa cria um item; aceita --username, --url, --generate e --kind
pfm edit NOME --agent-spaceo programa altera um item que programas criaram; as opções do edit, menos anexos e --agent
pfm get NOME --stdoutlê um valor; com --field totp, o código 2FA do momento
pfm codes NOME --stdoutimprime o próximo código de recuperação e o marca como usado
pfm list --agent-spaceo que o agente guarda, sem segredos
+
+
pfm unlock --for 8h --writable # você, uma vez, com a frase mestra
+
pfm add "acme teste admin" --agent-space --username admin@exemplo.com --url https://staging.exemplo.com --generate # o programa: conta com senha gerada
+
echo "$SENHA" | pfm add "acme teste usuario" --agent-space --username voce@exemplo.com # senha que o programa já tem, pelo stdin
+
pfm get "acme teste admin" --stdout # lê a senha de volta
+
echo "$SEGREDO_2FA" | pfm edit "acme teste usuario" --agent-space --totp # guarda o segredo do 2FA
+
pfm get "acme teste usuario" --field totp --stdout # o código 2FA de agora
+
printf '%s\n' "$CODIGO_1" "$CODIGO_2" | pfm edit "acme teste usuario" --agent-space --codes # guarda os códigos, um por linha
+
pfm codes "acme teste usuario" --stdout # gasta um código
+
pfm list --agent-space # o que o agente guarda
+
pfm status # mostra se o agente aceita escrita e quantas mudanças esperam
+
+

Cada segredo entra por uma linha do stdin, nunca como argumento. O que o programa grava fica cifrado no notebook, e o seu próximo comando no terminal (qualquer um: pfm list, pfm get…) traz esses itens para o cofre e sincroniza. No pfm list eles aparecem como agent-made na coluna AGENT.

+
    +
  • Os seus itens ficam fora do alcance: edit --agent-space e codes --stdout recusam um item que você criou, marcado ou não.
  • +
  • Um item seu sempre ganha a busca: se um programa criar um item chamado router, pfm get router continua achando o seu OpenRouter.
  • +
  • Apagar é com você: programas não apagam nem anexam arquivos. Use pfm rm NOME.
  • +
  • Limites: até 200 itens criados por programas, de até 64 KiB cada.
  • +
+

Depois de reiniciar o computador ou de um pfm lock, 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 pfm unlock --writable. Trate o que um programa guardou como vindo de fora: pode ter sido escrito pela aplicação que ele estava testando.

+
diff --git a/src/guide.html b/src/guide.html index ec4ce75..a38889c 100644 --- a/src/guide.html +++ b/src/guide.html @@ -147,10 +147,11 @@

pfm totp NOME código 2FA

pfm codes NOME código de recuperação

-

Copia o próximo código ainda não usado e o marca como usado. Avisa quando restam dois ou menos. Com --list, mostra todos e quais já foram usados (na tela, em texto puro). Para cadastrar os códigos, ver códigos de recuperação.

+

Copia o próximo código ainda não usado e o marca como usado. Avisa quando restam dois ou menos. Com --list, mostra todos e quais já foram usados (na tela, em texto puro). Com --stdout, imprime o código sozinho em vez de copiar, para programas (ver Agente). Para cadastrar os códigos, ver códigos de recuperação.

pfm codes openai # copia o próximo e marca como usado
pfm codes openai --list # todos, com (used) nos usados
+
pfm codes openai --stdout # o código sozinho, sem copiar

Não há como desmarcar um código: rode pfm codes 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 pfm edit NOME --codes.

@@ -464,7 +465,7 @@

pfm passwd trocar a frase mestra

Agente (programas)

-

Programas (scripts, agentes de IA) não usam a sessão. Eles só leem os itens que você marcar, e nada mais do cofre.

+

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.

@@ -485,6 +486,39 @@

Agente (programas)

Sem agente liberado, o get --stdout fora de um terminal falha na hora, em vez de ficar esperando uma frase que ninguém vai digitar.

+
+

pfm unlock --writable programas que guardam o que criam

+

Com --writable, 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 --agent.

+
+ + + + + + + +
ComandoO que faz
pfm unlock --writablevocê, no terminal: libera a leitura e a escrita por 8 horas (aceita --for e nomes de itens, como sempre)
pfm add NOME --agent-spaceo programa cria um item; aceita --username, --url, --generate e --kind
pfm edit NOME --agent-spaceo programa altera um item que programas criaram; as opções do edit, menos anexos e --agent
pfm get NOME --stdoutlê um valor; com --field totp, o código 2FA do momento
pfm codes NOME --stdoutimprime o próximo código de recuperação e o marca como usado
pfm list --agent-spaceo que o agente guarda, sem segredos
+
+
pfm unlock --for 8h --writable # você, uma vez, com a frase mestra
+
pfm add "acme teste admin" --agent-space --username admin@exemplo.com --url https://staging.exemplo.com --generate # o programa: conta com senha gerada
+
echo "$SENHA" | pfm add "acme teste usuario" --agent-space --username voce@exemplo.com # senha que o programa já tem, pelo stdin
+
pfm get "acme teste admin" --stdout # lê a senha de volta
+
echo "$SEGREDO_2FA" | pfm edit "acme teste usuario" --agent-space --totp # guarda o segredo do 2FA
+
pfm get "acme teste usuario" --field totp --stdout # o código 2FA de agora
+
printf '%s\n' "$CODIGO_1" "$CODIGO_2" | pfm edit "acme teste usuario" --agent-space --codes # guarda os códigos, um por linha
+
pfm codes "acme teste usuario" --stdout # gasta um código
+
pfm list --agent-space # o que o agente guarda
+
pfm status # mostra se o agente aceita escrita e quantas mudanças esperam
+
+

Cada segredo entra por uma linha do stdin, nunca como argumento. O que o programa grava fica cifrado no notebook, e o seu próximo comando no terminal (qualquer um: pfm list, pfm get…) traz esses itens para o cofre e sincroniza. No pfm list eles aparecem como agent-made na coluna AGENT.

+
    +
  • Os seus itens ficam fora do alcance: edit --agent-space e codes --stdout recusam um item que você criou, marcado ou não.
  • +
  • Um item seu sempre ganha a busca: se um programa criar um item chamado router, pfm get router continua achando o seu OpenRouter.
  • +
  • Apagar é com você: programas não apagam nem anexam arquivos. Use pfm rm NOME.
  • +
  • Limites: até 200 itens criados por programas, de até 64 KiB cada.
  • +
+

Depois de reiniciar o computador ou de um pfm lock, 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 pfm unlock --writable. Trate o que um programa guardou como vindo de fora: pode ter sido escrito pela aplicação que ele estava testando.

+
@@ -626,10 +660,11 @@

pfm totp NAME 2FA code

pfm codes NAME recovery code

-

Copies the next unused code and marks it used. Warns when two or fewer are left. With --list, shows them all and which were used (on screen, in plain text). To add the codes, see recovery codes.

+

Copies the next unused code and marks it used. Warns when two or fewer are left. With --list, shows them all and which were used (on screen, in plain text). With --stdout, prints the code alone instead of copying it, for programs (see Agent). To add the codes, see recovery codes.

pfm codes openai # copies the next one and marks it used
pfm codes openai --list # all of them, (used) on the used ones
+
pfm codes openai --stdout # the code alone, not copied

A code cannot be unmarked: run pfm codes 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 pfm edit NAME --codes.

@@ -943,7 +978,7 @@

pfm passwd change the master phrase

Agent (programs)

-

Programs (scripts, AI agents) don't use the session. They only read the items you mark, and nothing else in the vault.

+

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.

@@ -964,6 +999,39 @@

Agent (programs)

With no agent released, get --stdout outside a terminal fails at once, instead of waiting for a phrase nobody will type.

+
+

pfm unlock --writable programs that keep what they create

+

With --writable, 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 --agent.

+
+ + + + + + + +
CommandWhat it does
pfm unlock --writableyou, in a terminal: releases reading and writing for 8 hours (takes --for and item names, as always)
pfm add NAME --agent-spacethe program creates an item; takes --username, --url, --generate and --kind
pfm edit NAME --agent-spacethe program changes an item programs created; the options of edit, except attachments and --agent
pfm get NAME --stdoutreads a value; with --field totp, the current 2FA code
pfm codes NAME --stdoutprints the next recovery code and marks it used
pfm list --agent-spacewhat the agent holds, without secrets
+
+
pfm unlock --for 8h --writable # you, once, with the master phrase
+
pfm add "acme test admin" --agent-space --username admin@example.com --url https://staging.example.com --generate # the program: an account with a generated password
+
echo "$PASSWORD" | pfm add "acme test user" --agent-space --username you@example.com # a password the program already has, on stdin
+
pfm get "acme test admin" --stdout # reads the password back
+
echo "$TOTP_SECRET" | pfm edit "acme test user" --agent-space --totp # keeps the 2FA secret
+
pfm get "acme test user" --field totp --stdout # the 2FA code right now
+
printf '%s\n' "$CODE_1" "$CODE_2" | pfm edit "acme test user" --agent-space --codes # keeps the codes, one per line
+
pfm codes "acme test user" --stdout # uses one code
+
pfm list --agent-space # what the agent holds
+
pfm status # shows whether the agent takes writes and how many changes wait
+
+

Each secret comes in on a line of stdin, never as an argument. What the program writes stays encrypted on the laptop, and your next command in a terminal (any of them: pfm list, pfm get…) brings those items into the vault and syncs. In pfm list they show as agent-made in the AGENT column.

+
    +
  • Your items stay out of reach: edit --agent-space and codes --stdout refuse an item you created, marked or not.
  • +
  • An item of yours always wins a search: if a program creates an item called router, pfm get router still finds your OpenRouter.
  • +
  • Deleting is yours: programs neither delete nor attach files. Use pfm rm NAME.
  • +
  • Limits: up to 200 items created by programs, of up to 64 KiB each.
  • +
+

After a reboot or a pfm lock, what was written is not lost: it enters the vault with your next command. The program reads and writes again only after a new pfm unlock --writable. Treat what a program stored as coming from outside: it may have been written by the application it was testing.

+