> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Proteger CLI

> Registre impressões digitais de arquivos de uma conta de consumidor ou espaço de trabalho comercial e, em seguida, verifique o arquivo original.

Registre a impressão digital SHA-256 de um arquivo e verifique-o posteriormente com Truthlocks. Os arquivos são
hash localmente: a CLI envia a impressão digital e os metadados do registro, não o conteúdo do arquivo.

**Tempo de execução:** Node.js 18+ · **Pacote:** `@truthlocks/protect` · **Comando:** `truthlock-protect`

[Console](https://console.truthlocks.com) · [Aplicativo do consumidor](https://verify.truthlocks.com) · [Documentação da API](https://docs.truthlocks.com)

## Instalar

```sh theme={null}
npm install --global @truthlocks/protect
truthlock-protect --help
```

O comando `truthlocks` também é instalado como um alias. Este pacote registra online
impressões digitais; use `@truthlocks/cli` para verificação offline de pacotes de prova.

## Escolha o tipo da sua conta

| Conta | Credencial | Configuração de assinatura |
| - | - | - |
| Espaço de trabalho empresarial | `TRUTHLOCKS_API_KEY` | Um emissor ativo e uma chave disponível para assinatura no console. |
| Conta de consumidor | `TRUTHLOCK_TOKEN` | Um token de portador de consumidor autorizado; Truthlocks gerencia sua chave de assinatura. |

Uma chave de API não é um token de consumidor. A CLI usa endpoints diferentes para esses dois
fluxos de trabalho. As chaves de API de teste selecionam o host sandbox. Defina `TRUTHLOCK_API_URL` apenas quando
você intencionalmente precisa de uma origem de API diferente.

## Início rápido do espaço de trabalho

Defina `TRUTHLOCKS_API_KEY`, `TRUTHLOCKS_ISSUER_ID` e `TRUTHLOCKS_KEY_ID` em seu ambiente,
então proteja um arquivo existente:

```sh theme={null}
truthlock-protect whoami
truthlock-protect protect ./report.pdf --title "Quarterly report" --idempotency-key report-release-2026-10-11 --output ./report.receipt.json --json
```

Substitua a chave de repetição de exemplo por um valor único para esta operação. Mantenha-a com
os detalhes da solicitação e reutilizá-la apenas para a solicitação idêntica. A saída contém
`attestation_id` e `payload_b64url`; mantenha ambos. A opção `--output` salva um recibo sem sobrescrever um arquivo existente. Esta operação escreve um registro.

Você pode selecionar o emissor e a chave explicitamente, em vez disso:

```sh theme={null}
truthlock-protect protect ./report.pdf --issuer-id YOUR_ISSUER_UUID --key-id YOUR_SIGNING_KEY_ID --algorithm Ed25519 --json
```

Substitua os marcadores de posição em maiúsculas. O algoritmo deve corresponder à chave selecionada. Se
exatamente um emissor ativo e uma chave de assinatura elegível estão disponíveis, a CLI pode
selecioná-los automaticamente; caso contrário, ele solicita que você escolha usando sinalizadores.

Os registros do espaço de trabalho usam reivindicações estruturadas com uma impressão digital `document.sha256` e um
hash de documento explícito. Eles seguem as regras de acesso ao espaço de trabalho/API; a visibilidade do consumidor
flags não se aplicam a este fluxo de trabalho.

## Início rápido do consumidor

Defina `TRUTHLOCK_TOKEN` para um token de portador de consumidor autorizado, com chave de API do espaço de trabalho
variáveis de ambiente não definidas, então execute:

```sh theme={null}
truthlock-protect whoami
truthlock-protect protect ./design.png --title "Design source" --private --output ./design.receipt.json --json
```

Os registros do consumidor são privados por padrão. Use `--public` apenas quando quiser um público
registro do consumidor. O serviço seleciona a chave de assinatura do consumidor; `--algorithm`,
`--issuer-id` e `--key-id` são opções de espaço de trabalho e são rejeitadas no modo consumidor.

## Verificar um registro e arquivo

Use o recibo salvo e o arquivo original. O recibo fornece os bytes exatos
que foram assinados; o arquivo fornece a impressão digital para comparar:

```sh theme={null}
truthlock-protect verify --receipt ./report.receipt.json --file ./report.pdf --json
```

Para um registo de consumidor atual, pode reconstruir o seu personal-record-v2 definido
payload do arquivo original:

```sh theme={null}
truthlock-protect verify YOUR_ATTESTATION_UUID --personal-record --file ./design.png --json
```

Esta reconstrução é automática ao usar apenas um token de consumidor com `--file`.
Não reconstrói reivindicações arbitrárias de espaço de trabalho ou formatos de carga histórica.
Para um registo de espaço de trabalho sem um recibo guardado, forneça o payload assinado original
bytes usando `--payload-file ./signed-payload.json`. Não reformate esse JSON.

O código de saída 0 requer ambos `verdict: VALID` e `signature_verified: true`.
Arquivos alterados e provas incompletas saem com valor diferente de zero. Uma pesquisa somente por ID não pode verificar
uma assinatura; ele reporta `INCOMPLETE` a menos que um status mais forte, como revogação, se aplique:

```sh theme={null}
truthlock-protect verify YOUR_ATTESTATION_UUID --json
```

Um registro de impressão digital válido é uma evidência de que os bytes correspondem ao hash registrado. Ele não
não prova independentemente autoria, propriedade de direitos autorais ou a veracidade de seu título.

## Comandos

| Comando | Finalidade |
| - | - |
| `protect <file>` / `p <file>` | Registrar a impressão digital de um arquivo regular. |
| `verify [id] --receipt <path> --file <path>` | Verifique o payload assinado retido e compare os bytes do arquivo original. |
| `list [--limit 20] [--json]` | Ler registros disponíveis para a conta configurada. |
| `whoami` | Verificar acesso ao espaço de trabalho ou informações da conta do consumidor. |
| `login --token <token>` | Salvar um token de consumidor localmente. Variáveis de ambiente evitam salvá-lo. |
| `logout` | Remover o token de consumidor salvo; variáveis de ambiente e credenciais do espaço de trabalho permanecem. |
| `register --email <email>` | Registrar um espaço de trabalho de desenvolvedor e salvar sua chave de API sandbox. |

O registro de desenvolvedor é uma operação separada de criação de conta. Não cria
uma sessão de consumidor ou garantir que uma chave de emissor/assinatura já esteja provisionada.

## Opções e armazenamento local

`protect` aceita `--title`, `--description`, `--category`, `--content-type`, `--json`,
`--api-key`, `--issuer-id`, `--key-id`, `--algorithm`, `--idempotency-key` e `--output`.
`--public` e `--private` aplicam-se apenas a consumidores. A categoria do arquivo é detectada automaticamente, a menos que seja fornecida. Diretórios não são suportados.

A variável histórica `TRUTHLOCK_API_KEY` ainda é aceita. Sinalizadores explícitos de chave de API
e variáveis de ambiente têm prioridade sobre uma chave de desenvolvedor salva. Uma chave explícita
variável de ambiente consumer-token tem prioridade sobre uma chave de desenvolvedor salva quando
nenhuma variável de ambiente de chave de API é fornecida.

Um token de consumidor salvo reside em `~/.truthlock/config.json`; credenciais de desenvolvedor residem
em `~/.truthlocks/credentials.json`. Estes são arquivos de credenciais locais. Mantenha-os fora
de repositórios e backups destinados à publicação.

## Solução de problemas

| Mensagem ou resultado | Próximo passo |
| - | - |
| Nenhuma credencial | Configure a credencial para o tipo de conta pretendido. |
| Escolha um emissor ou chave | Forneça os IDs mostrados no console; confirme se a chave pode assinar. |
| Incompatibilidade de ambiente | Corresponda as chaves de teste/produção ao host de API correto. |
| As chaves de assinatura do consumidor são gerenciadas | Remova sinalizadores somente de espaço de trabalho ou use uma chave de API de espaço de trabalho. |
| `INCOMPLETE` | Forneça o recibo salvo ou o payload assinado exato; um ID ou hash de arquivo sozinho é insuficiente para assinaturas de espaço de trabalho. |
| `ALTERED` | Verifique se você forneceu o arquivo original exato. |
| Solicitação esgotou o tempo limite | Verifique o resultado da operação antes de tentar novamente; mantenha a chave de repetição original. |

As solicitações usam um tempo limite de 30 segundos e são enviadas uma vez. Redirecionamentos são rejeitados. Limite de taxa
valores restantes não são apresentados como uma cota mensal.

## Atualizando da versão 1.0

A versão 1.1.1 adiciona payloads assinados retidos e verificação criptográfica com arquivos originais. A versão 1.1 corrige cabeçalhos de chave de API, consumidor `content_hash`, assinatura de espaço de trabalho, privado
padrões do consumidor, saída JSON, aliases de comando e verificação real. Exemplos anteriores
que alegava que uma pesquisa de proteção era verificação criptográfica deve ser substituída.

Licença MIT.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.