Variáveis

Um ambiente é um conjunto nomeado de variáveis armazenado como JSON. Um workspace pode ter qualquer número de ambientes; um está “ativo” por vez. O ambiente ativo é registrado no arquivo de estado pessoal do workspace, então sobrevive a reinícios; se aquele ambiente não existir mais, o Fetchpier cai para o primeiro disponível.

As variáveis são usadas em:

Placeholders {{name}} na URL, nos cabeçalhos, no body e nos campos de formulário.
Campos de auth — o token Bearer, as credenciais Basic e os valores de API key podem todos referenciar variáveis. A senha do Basic auth é um campo secreto mascarado: um valor literal fica oculto enquanto você digita (com um breve reveal do último caractere), e o valor é exibido em texto claro apenas quando é exatamente uma referência {{variable}} completa — qualquer outro valor, incluindo um literal que comece com {, permanece mascarado.
Passphrases de TLS — a passphrase de um certificado de cliente de workspace pode ser um placeholder {{name}}, plano ou secreto, então as credenciais ficam no ambiente e não em arquivos commitados. Os certificados globais do app continuam apenas literais — veja TLS e certificados.

Onde quer que um segredo seja digitado atrás de um mascaramento — a passphrase do certificado, a senha do Basic auth, a senha do proxy — vale a mesma regra: os caracteres ficam ocultos, e o último caractere digitado é exibido brevemente para ajudar a confirmar o que foi inserido. Nos campos que também aceitam variáveis (a passphrase do certificado do workspace e a senha do Basic auth), o valor é exibido em texto claro apenas quando é exatamente uma referência {{variable}} completa; qualquer outro valor permanece mascarado — a mesma regra que decide o aviso de passphrase literal em texto claro, então os dois nunca discordam.

Pre-request scripts podem mutar variáveis de ambiente com fp.environment.set('token', value), e o Fetchpier persiste essas mudanças depois da resposta, então as requisições seguintes veem o valor novo. Cada envio também tem um espaço scratch efêmero de “variables” (fp.variables.*) que vive apenas durante aquele envio — útil para passar valores entre o pre-request e o post-response script da mesma chamada sem poluir o ambiente persistido.

Para a ordem de resolução quando várias fontes definem o mesmo nome, veja Precedência de variáveis.

Obter valores do SO ou de um arquivo `.env`

O valor de uma variável pode referenciar o ambiente do host com {{$env.NAME}}. A referência é resolvida em cada envio contra uma cadeia de fontes fixa:

O arquivo .env do workspace (se existir). Quando a chave existe no .env — inclusive com valor vazio — aquele valor ganha, mesmo sobre o shell do SO.
O ambiente do processo Fetchpier (ou fp) em execução.
A string vazia quando nenhuma das fontes define a chave. A requisição sai de qualquer forma, com o buraco não resolvido visível no payload de saída (p. ex. Authorization: Bearer ).

Essa é a forma suportada de manter o config.json de um ambiente commitável sem deixar segredos no repositório: o JSON contém "apiKey": "{{$env.OPENAI_KEY}}", e o segredo vive no .env (ignorado pelo Git por padrão) ou no shell do operador.

{{$env.NAME}} é reconhecido apenas dentro dos valores de variáveis de ambiente. Colocado diretamente na URL, em um cabeçalho, no body ou em um script de um .http, ele fica literal — os ambientes são o único lugar canônico para segredos.

O arquivo .env usa o formato dotenv: KEY=VALUE por linha, quoting "…" (com escapes \n \r \t \\ \") e '…' (literal), comentários # no início da linha ou inline após um espaço, linhas vazias ignoradas, duplicados resolvidos por last-wins. Expansão de variáveis dentro do .env não é suportada. Arquivos maiores que 1 MiB ou que não sejam UTF-8 são ignorados com um aviso. Não há watcher: cada envio relê o arquivo.

O editor de ambientes sempre mostra o valor cru armazenado (p. ex. {{$env.OPENAI_KEY}}), nunca o valor resolvido, então o segredo vivo nunca aparece na UI.

Variáveis secretas (criptografadas, commitáveis)

Qualquer variável de ambiente pode ser marcada como secreta. Seu valor é criptografado no lugar com uma chave por workspace e armazenado como ciphertext no mesmo mapa de variáveis das planas, então o ambiente — credenciais incluídas — pode ser commitado e compartilhado pelo Git sem vazar nada. Marcar uma variável como secreta reescreve seu valor no lugar, então um diff de Git da operação mostra um único valor mudando, não uma chave se movendo. Valores planos que começam com enc: são reservados (esse prefixo marca segredos criptografados) e são rejeitados na entrada, tanto no editor quanto em scripts.

Esse é o complemento in-repo do {{$env.NAME}}: use {{$env.NAME}} para manter um segredo totalmente fora do repo, ou uma variável secreta para a credencial viajar com o repo como ciphertext.

A chave do workspace. Na primeira vez que uma variável é marcada como secreta, o Fetchpier gera uma chave de workspace de 32 bytes e a mostra uma única vez, em uma forma agrupada legível por humanos (FPK1-…), para backup. Esse é o único momento em que a chave é exibida — depois não há nenhuma tela de “mostrar chave”. Todos os colegas de equipe e todas as outras máquinas precisam dela; o Fetchpier não pode recuperá-la, então guarde-a (um gerenciador de senhas) e compartilhe-a por um canal separado. Um manifest do workspace commitado em .fetchpier/secrets.json permite que qualquer clone verifique uma chave inserida sem expor nada.

Abrir um workspace compartilhado. Um clone cuja máquina ainda não tem a chave a solicita; a chave é validada contra o manifest. Até ser inserida, o workspace fica bloqueado: tudo funciona exceto enviar uma requisição que referencie um segredo, que falha com um erro claro de “sem chave”. Uma vez inserida, a chave é lembrada em máquinas com keyring do SO. No Linux sem keyring, o Fetchpier se recusa a persistir sob um fallback inefetivo e mantém a chave apenas para a sessão, pedindo novamente na próxima inicialização.

Usar e revelar. Uma vez desbloqueado, variáveis secretas se interpolam exatamente como as planas. No editor um segredo é renderizado mascarado com um olho para revelá-lo sob demanda; no macOS com Touch ID o reveal pede confirmação por impressão digital (com uma curta janela de tolerância), e nas outras plataformas revela diretamente. Um segredo também pode ficar sem valor neste workspace (um estado de “precisa de valor”): seu nome e seu caráter secreto viajam pelo Git como template, e uma requisição que o referencie falha de forma precisa até um valor ser inserido.

Mascaramento. Valores secretos nunca aparecem em nenhum artefato que o Fetchpier escreva. O log de atividade, todos os reporters de CLI e as visões de requisição resolvida renderizam um segredo como {secret:<name>} e marcam a entrada como redigida; o valor real vai apenas pela rede. Se um servidor devolver um segredo na resposta, o Fetchpier o mascara na resposta logada na medida do possível. Scripts são código confiável, então um script que leia o plaintext de um segredo e o transforme pode produzir saída que o mascaramento não reconheça.

Rotação. “Rotacionar a chave do workspace” gera uma chave nova, recriptografa atomicamente cada segredo de todos os ambientes, e mostra a chave nova uma vez para redistribuição. A rotação não revoga quem já tinha a chave antiga, nem muda as credenciais subjacentes em seus provedores — o diálogo de confirmação afirma as duas coisas. Da mesma forma, criptografar uma variável que já tinha um valor a protege de agora em diante mas não remove as cópias já presentes no histórico do Git; se ela já foi enviada em um push, rotacione a credencial no provedor. O editor mostra essa nota antes de criptografar.

Apagar um segredo. Uma linha secreta oferece uma ação direta de apagar (lixeira), então uma credencial pode ser removida em um único gesto — sem convertê-la antes em texto plano. Apagar remove a variável como ciphertext (ela nunca é descriptografada, e funciona mesmo com o workspace bloqueado) e também remove qualquer valor local definido para esse nome nesta máquina. A confirmação é honesta sobre a reversibilidade: para um segredo criptografado, afirma claramente que o valor não pode ser recuperado sem o original (e nunca mostra o valor); para um segredo em “precisa de valor” é mais leve, já que não há nada criptografado a perder. Apagar um segredo nunca toca a chave do workspace, mesmo que fosse o último segredo — a custódia da chave vive apenas na aba Workspace keys. Isso é diferente de tornar um segredo plano, que o converte em uma variável em texto plano commitada e mantém a linha.

Uma chave vazada (não o ciphertext) é o único acidente contra o qual a criptografia não pode defender. Uma regra de scanner pronta para copiar e colar para o formato FPK1- é fornecida para que as equipes possam detectar uma chave commitada por engano.

Gerenciar as chaves desta máquina

Uma aba Workspace keys nas configurações gerais lista cada chave de workspace que esta máquina guarda, mostrando a dica de cada uma, o id curto da chave, quando foi usada pela última vez e como está armazenada (“Stored” ou, em modo degradado, “This session only”). Navegar pela lista nunca pede um keychain nem uma passphrase — ela mostra apenas metadados e nunca revela, copia ou exporta uma chave. Para cada chave, um status diz se algum workspace que esta app conhece ainda a referencia: “In use” (nomeando os workspaces), “Not referenced” (nunca formulado como inválida ou sem uso — um clone que esta app nunca viu ainda pode precisar dela) ou “Could not check” quando um workspace conhecido não pôde ser lido. A partir da aba você pode:

Apagar uma chave — com proteção, porque a exclusão pode ser definitiva. Se a chave está sabidamente em uso por um workspace que esta app referencia, a exclusão é bloqueada, com a orientação de remover antes os segredos dependentes daquele workspace. Caso contrário, a confirmação afirma a consequência claramente — a chave existe apenas nesta máquina, então cada segredo criptografado com ela se torna permanentemente irrecuperável a menos que seu backup de exibição única seja inserido novamente —, mostra o nome do workspace afetado como texto copiável, e só habilita a exclusão depois que você digita esse nome para confirmar. A ausência de uma referência conhecida nunca bloqueia a exclusão: um clone que esta app nunca viu não pode ser descartado, então esse caso cai na confirmação digitada em vez de um bloqueio rígido.
Adicionar uma chave com antecedência — cole uma chave FPK1-… (com uma dica opcional) antes de clonar seu workspace, p. ex. uma que um colega compartilhou durante o onboarding. A chave é verificada contra erros de digitação (checksum) na entrada; quando o workspace é aberto depois, ele desbloqueia sem pedir nada e seu status passa para “In use”. Colar de novo uma chave que você já tem não faz nada; o caso raro de uma chave diferente sob o mesmo id (ou de uma cópia armazenada que se tornou ilegível) oferece substituí-la.

Valores locais (apenas esta máquina)

Cada ambiente tem duas camadas de valores, exibidas lado a lado no editor como uma coluna Shared e uma coluna Local:

Shared é o ambiente da equipe — commitado e compartilhado pelo Git, tanto variáveis planas quanto secretas.
Local é uma camada sobreposta por máquina que nunca é compartilhada. Ela é excluída do Git por padrão e contém dois tipos de valores: um override pessoal de uma variável compartilhada, e uma variável não compartilhada, que existe na sua máquina e em lugar nenhum do arquivo da equipe. Quando ambas as camadas têm um valor para um nome, o local ganha.

Um valor só viaja da camada compartilhada para a local, nunca de volta. Desmarcar Sync copia o valor da equipe para a sua camada local; nada copia um valor local para cima. A única forma de um valor chegar à equipe é você digitá-lo na célula Shared. Essa única regra é o que torna todo outro gesto seguro: nenhum checkbox, nenhuma ação em massa e nenhum script podem publicar um valor privado no arquivo que sua equipe commita.

O caráter secreto é uma propriedade da variável, não de uma camada: marcar uma variável como secreta a torna secreta em ambas as colunas ao mesmo tempo. Um valor local de uma variável com nome secreto é criptografado com a mesma chave de workspace; um valor local de uma variável plana é armazenado como texto plano, já que o arquivo é seu e nunca sai da máquina.

Dois caminhos escrevem a camada local, e apenas a camada local:

Scripts. fp.environment.set(name, value) escreve na camada local e persiste entre reinícios — o uso canônico é um pre-request script que renova um access token para o próximo envio. Scripts nunca escrevem o arquivo compartilhado da equipe.
O editor. Cada linha de variável carrega um check Sync. Marcado significa que a variável segue o valor compartilhado e a célula Local é somente leitura, então você não pode divergir por acidente ao digitar. Desmarcá-lo é o ato deliberado de divergir: cria um valor local semeado com o valor compartilhado atual (ou, para um segredo em “precisa de valor”, um campo vazio para sua própria credencial). Marcá-lo novamente devolve a variável ao valor compartilhado atual da equipe, descartando o seu — pede confirmação apenas quando os dois realmente diferem. Uma ação Sync all devolve todas as variáveis divergidas de uma só vez.

As variáveis não compartilhadas — um nome na sua camada local sem contrapartida no arquivo da equipe — são tratadas como um estado não resolvido, não como um tipo de variável. A linha fica no fim da lista com sua célula Shared vazia dizendo “Not shared — type to share”, uma barra de acento na sua borda dianteira, e um tooltip que explica isso. Digitar um valor na célula Shared dá à equipe aquela variável enquanto seu valor local permanece e continua ganhando para você; marcar Sync descarta o valor local e avisa primeiro que a variável ficará vazia, observando que digitar antes um valor compartilhado o preservaria. Nada mais escreve o arquivo da equipe: editar outras variáveis, reordenar, abrir e fechar o editor e enviar requisições deixam um nome não compartilhado exatamente onde está.

Tornar secreta uma variável não compartilhada criptografa seu valor local no lugar e marca a variável no arquivo da equipe como um segredo que precisa de valor — cada colega fornece o seu. Bloquear declara o caráter secreto, não o compartilhamento; seu valor não é publicado. Apagar uma variável a remove de ambas as camadas, então ela não pode voltar como uma linha não compartilhada.

Valores locais são pessoais e regeneráveis, o que molda dois comportamentos em torno da chave do workspace. Em uma rotação — feita aqui ou por um colega cuja mudança você puxou — o Fetchpier recriptografa silenciosamente seus valores locais criptografados para a chave nova na próxima vez que o ambiente carregar; se a chave antiga não estiver mais na máquina, os valores locais afetados são descartados com um aviso único e a variável cai para seu valor compartilhado. Rodar fp run pela linha de comando lê e aplica os valores locais de forma idêntica mas nunca os reescreve: em CI, um valor local desatualizado é simplesmente avisado e ignorado naquela execução, então uma execução nunca modifica um workspace já feito checkout.

Variáveis dinâmicas (geradas pelo sistema)

Além das variáveis que você define, o Fetchpier oferece um conjunto fixo de variáveis dinâmicas endereçadas como {{$name}}: tokens embutidos que resolvem para dados aleatórios recém-gerados no momento do envio, então você pode colocar um valor descartável (uma chave de idempotência única, um UUID novo para um body de POST, o timestamp atual em um cabeçalho) exatamente onde ele é consumido, em vez de hardcodar um literal ou escrever um script.

O conjunto v1 é puramente algorítmico, sem dados curados: {{$guid}} / {{$randomUUID}} (um UUID v4), {{$timestamp}} (segundos UNIX) e {{$isoTimestamp}} (ISO-8601 UTC), {{$randomInt}} (0–1000), {{$randomBoolean}}, {{$randomAlphaNumeric}} (um caractere), {{$randomHexColor}}, {{$randomIP}} / {{$randomIPV6}}, {{$randomMACAddress}}, {{$randomPassword}} (15 caracteres) e {{$randomSemver}}. Os nomes são case-sensitive.

Novos sempre. Cada ocorrência textual gera seu próprio valor, e cada envio regenera — {{$guid}} em um cabeçalho e no body dá dois UUIDs diferentes no mesmo envio. Nada é armazenado: o arquivo .http sempre mostra o token, nunca um valor gerado, e nenhum ambiente é tocado. O runner de linha de comando os resolve de forma idêntica.
Onde aparecem. A lista de sugestões de {{ os mostra depois das suas próprias variáveis, em uma única lista plana, marcados com um ícone de dado e uma cor dedicados; digitar $ filtra a lista apenas para as variáveis dinâmicas. Nos editores, um token dinâmico reconhecido recebe sua própria terceira cor de destaque, distinta da de uma variável resolvida (verde) e da de uma desconhecida (vermelho).
Tokens $ desconhecidos. Um {{$notARealOne}} é tratado como qualquer variável não resolvida: fica literal na rede, é sinalizado na UI, e o envio prossegue de qualquer forma.
Log de atividade. Como os valores não são segredos, o valor gerado aparece sem mascaramento no log de atividade, nos snapshots de execução e nos relatórios de CLI — um registro fiel do que saiu pela rede, embora, sendo aleatório, um snapshot não seja reexecutável para o mesmo valor.

Todo o prefixo $ é reservado para esses tokens do sistema: um nome de variável de usuário que comece com $ é rejeitado na entrada, tanto no editor de ambientes quanto em scripts (fp.environment.set('$x', …) lança erro).