> ## 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 las huellas digitales de los archivos de una cuenta de consumidor o espacio de trabajo empresarial, luego verifique el archivo original.

Registre la huella digital SHA-256 de un archivo y verifíquela más tarde con Truthlocks. Los archivos son
hasheado localmente: la CLI envía la huella digital y los metadatos del registro, no el contenido del archivo.

**Tiempo de ejecución:** Node.js 18+ · **Paquete:** `@truthlocks/protect` · **Comando:** `truthlock-protect`

[Console](https://console.truthlocks.com) · [Aplicación para consumidores](https://verify.truthlocks.com) · [Documentación de la API](https://docs.truthlocks.com)

## Instalar

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

El comando `truthlocks` también se instala como un alias. Este paquete registra en línea
huellas dactilares; use `@truthlocks/cli` para la verificación de paquetes de prueba fuera de línea.

## Elegir su tipo de cuenta

| Cuenta | Credencial | Configuración de firma |
| - | - | - |
| Espacio de trabajo empresarial | `TRUTHLOCKS_API_KEY` | Un emisor activo y una clave disponible para firmar en la consola. |
| Cuenta de consumidor | `TRUTHLOCK_TOKEN` | Un token de portador de consumidor autorizado; Truthlocks gestiona su clave de firma. |

Una clave API no es un token de consumidor. La CLI utiliza diferentes puntos finales para estos dos
flujos de trabajo. Las claves API de prueba seleccionan el host de sandbox. Establezca `TRUTHLOCK_API_URL` solo cuando
necesite intencionalmente un origen de API diferente.

## Inicio rápido del espacio de trabajo

Establezca `TRUTHLOCKS_API_KEY`, `TRUTHLOCKS_ISSUER_ID` y `TRUTHLOCKS_KEY_ID` en su entorno,
luego proteger un archivo 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
```

Reemplace la clave de reintento de ejemplo con un valor único para esta operación. Consérvela con
los detalles de la solicitud y reutilizarla solo para la solicitud idéntica. La salida contiene
`attestation_id` y `payload_b64url`; conserve ambos. La opción `--output` guarda un recibo sin sobrescribir un archivo existente. Esta operación escribe un registro.

Puede seleccionar el emisor y la clave explícitamente en su lugar:

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

Reemplace los marcadores de posición en mayúsculas. El algoritmo debe coincidir con la clave seleccionada. Si
exactamente un emisor activo y una clave de firma elegible están disponibles, la CLI puede
seleccionarlos automáticamente; de lo contrario, le pedirá que elija usando banderas.

Los registros del espacio de trabajo utilizan reclamaciones estructuradas con una huella digital `document.sha256` y un
hash de documento explícito. Siguen las reglas de acceso al espacio de trabajo/API; la visibilidad del consumidor
las banderas no se aplican a este flujo de trabajo.

## Inicio rápido para el consumidor

Establezca `TRUTHLOCK_TOKEN` en un token de portador de consumidor autorizado, con clave API del espacio de trabajo
variables de entorno sin establecer, luego ejecute:

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

Los registros de consumidores son privados por defecto. Use `--public` solo cuando desee un público
registro del consumidor. El servicio selecciona la clave de firma del consumidor; `--algorithm`,
`--issuer-id` y `--key-id` son opciones del espacio de trabajo y se rechazan en modo consumidor.

## Verificar un registro y un archivo

Utilice el recibo guardado y el archivo original. El recibo proporciona los bytes exactos
que fueron firmados; el archivo proporciona la huella digital para comparar:

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

Para un registro de consumidor actual, puede reconstruir su personal-record-v2 definido
carga útil del archivo original:

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

Esta reconstrucción es automática cuando se utiliza solo un token de consumidor con `--file`.
No reconstruye reclamaciones de espacio de trabajo arbitrarias ni formatos de carga útil históricos.
Para un registro de espacio de trabajo sin un recibo guardado, proporcione la carga útil firmada original
bytes usando `--payload-file ./signed-payload.json`. No reformatee ese JSON.

El código de salida 0 requiere tanto `verdict: VALID` como `signature_verified: true`.
Los archivos alterados y las pruebas incompletas salen con un valor distinto de cero. Una búsqueda solo por ID no puede verificar
una firma; informa `INCOMPLETE` a menos que se aplique un estado más fuerte como la revocación:

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

Un registro de huella digital válido es evidencia de que los bytes coinciden con el hash registrado. No lo hace
no prueba de forma independiente la autoría, la propiedad de los derechos de autor o la veracidad de su título.

## Comandos

| Comando | Propósito |
| - | - |
| `protect <file>` / `p <file>` | Registrar la huella digital de un archivo regular. |
| `verify [id] --receipt <path> --file <path>` | Verifique la carga útil firmada retenida y compare los bytes del archivo original. |
| `list [--limit 20] [--json]` | Leer registros disponibles para la cuenta configurada. |
| `whoami` | Comprobar el acceso al espacio de trabajo o la información de la cuenta del consumidor. |
| `login --token <token>` | Guardar un token de consumidor localmente. Las variables de entorno evitan guardarlo. |
| `logout` | Eliminar el token de consumidor guardado; las variables de entorno y las credenciales del espacio de trabajo permanecen. |
| `register --email <email>` | Registre un espacio de trabajo de desarrollador y guarde su clave API de sandbox. |

El registro de desarrollador es una operación de creación de cuenta separada. No crea
una sesión de consumidor o garantizar que una clave de emisor/firma ya esté provisionada.

## Opciones y almacenamiento local

`protect` acepta `--title`, `--description`, `--category`, `--content-type`, `--json`,
`--api-key`, `--issuer-id`, `--key-id`, `--algorithm`, `--idempotency-key` y `--output`.
`--public` y `--private` se aplican solo a los consumidores. La categoría de archivo se detecta automáticamente a menos que se proporcione. Los directorios no son compatibles.

La variable histórica `TRUTHLOCK_API_KEY` todavía se acepta. Banderas explícitas de clave API
y las variables de entorno tienen prioridad sobre una clave de desarrollador guardada. Una clave explícita
la variable de entorno del token de consumidor tiene prioridad sobre una clave de desarrollador guardada cuando
no se proporciona ninguna variable de entorno de clave API.

Un token de consumidor guardado reside en `~/.truthlock/config.json`; las credenciales de desarrollador residen
en `~/.truthlocks/credentials.json`. Estos son archivos de credenciales locales. Manténgalos fuera
de repositorios y copias de seguridad destinadas a la publicación.

## Solución de problemas

| Mensaje o resultado | Siguiente paso |
| - | - |
| Sin credenciales | Configure la credencial para el tipo de cuenta previsto. |
| Elegir un emisor o clave | Suministre los ID que se muestran en la consola; confirme que la clave puede firmar. |
| Desajuste de entorno | Haga coincidir las claves de prueba/producción con el host de API correcto. |
| Las claves de firma del consumidor se gestionan | Elimine las banderas de solo espacio de trabajo o use una clave API de espacio de trabajo. |
| `INCOMPLETE` | Suministre el recibo guardado o la carga útil firmada exacta; un ID o hash de archivo por sí solo es insuficiente para las firmas del espacio de trabajo. |
| `ALTERED` | Verifique que suministró el archivo original exacto. |
| Solicitud agotó el tiempo de espera | Verifique el resultado de la operación antes de reintentar; conserve la clave de reintento original. |

Las solicitudes utilizan un tiempo de espera de 30 segundos y se envían una vez. Las redirecciones son rechazadas. Límite de velocidad
los valores restantes no se presentan como una cuota mensual.

## Actualización desde la versión 1.0

La versión 1.1.1 añade cargas útiles firmadas retenidas y verificación criptográfica con archivos originales. La versión 1.1 corrige los encabezados de la clave API, el consumidor `content_hash`, la firma del espacio de trabajo, privado
valores predeterminados del consumidor, salida JSON, alias de comandos y verificación real. Ejemplos anteriores
que afirmaba que una búsqueda de protección era verificación criptográfica debería ser reemplazada.

Licencia MIT.


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