CLI Commands

This page documents all available Sentinel CLI subcommands and their usage patterns.

Initialize a Store

Creates a new Sentinel store at the specified path with the necessary directory structure and metadata.

Usage:

sentinel init --path <PATH> [OPTIONS]

Required Arguments:

-p, --path <PATH>: Path to the store directory

Optional Arguments:

--passphrase <PASSPHRASE>: Passphrase for encrypting the signing key
--signing-key <KEY>: Hex-encoded signing key to use. If not provided, a new one is generated if initializing a new store

Examples:

# Initialize a new store
sentinel init --path /data/my-store

# Initialize with a specific signing key
sentinel init --path /data/my-store --signing-key 1234abcd...

# Initialize with passphrase protection
sentinel init --path /data/my-store --passphrase "my-secure-passphrase"

# Combine all options
sentinel init --path /data/my-store \
  --passphrase "my-secure-passphrase" \
  --signing-key 1234abcd... \
  --encryption-algorithm aes256gcmsiv

What It Does:

Creates the store directory if it doesn’t exist
Initializes metadata files
Generates or imports a signing key
Optionally encrypts the signing key with the provided passphrase
Sets up the internal .keys collection for key storage (if applicable)

Generate Cryptographic Keys

Generates cryptographic keys and other artifacts for use with Sentinel.

Tip: The generate command can be abbreviated as gen.

Generate a Cryptographic Key

Generates a new cryptographic key of the specified type and outputs it as a hex string.

Usage:

sentinel generate key <KEY_TYPE>
sentinel gen key <KEY_TYPE>

Key Types:

signing Generate an Ed25519 signing key pair
encryption Generate a 256-bit encryption key

Examples:

# Generate a signing key
sentinel generate key signing
# Output: 1a2b3c4d5e6f...

# Generate an encryption key
sentinel gen key encryption
# Output: 9f8e7d6c5b4a...

# Save to a file
sentinel gen key signing > signing-key.txt

# Use with init command
SIGNING_KEY=$(sentinel gen key signing)
sentinel init --path /data/my-store --signing-key $SIGNING_KEY

Create a Collection

Creates a new collection within an existing store. Refer to the Collection API for more details.

Usage:

sentinel create-collection --store <STORE_PATH> --name <COLLECTION_NAME>

Required Arguments:

-s, --store <STORE_PATH> - Path to the store directory
-n, --name <COLLECTION_NAME> - Name of the collection to create

Examples:

# Create a users collection
sentinel create-collection --store /data/my-store --name users

# Create an audit logs collection
sentinel create-collection --store /data/my-store --name audit_logs

# Create with custom encryption
sentinel create-collection \
  --store /data/my-store \
  --name sensitive-data \
  --encryption-algorithm aes256gcmsiv

What It Does:

Creates a subdirectory within the store for the collection
Initializes collection metadata (.metadata.json)
Sets up subdirectories for indices, deleted documents, and WAL

Insert a Document

Inserts a new document into a collection. The document must be valid JSON.

Usage:

sentinel insert --store <STORE_PATH> --collection <COLLECTION_NAME> --id <DOCUMENT_ID> --data <JSON_DATA>

Required Arguments:

-s, --store <STORE_PATH>: Path to the store directory
-c, --collection <COLLECTION_NAME>: Name of the collection
-i, --id <DOCUMENT_ID>: Unique identifier for the document
-d, --data <JSON_DATA>: JSON data for the document

Examples:

# Insert a simple document
sentinel insert \
  --store /data/my-store \
  --collection users \
  --id user-123 \
  --data '{"name": "Alice", "email": "[email protected]"}'

# Insert from a file
sentinel insert \
  --store /data/my-store \
  --collection users \
  --id user-456 \
  --data "$(cat user.json)"

# Insert with verbose logging
sentinel insert -v \
  --store /data/my-store \
  --collection audit_logs \
  --id audit-2026-01-15 \
  --data '{"action": "login", "user": "bob", "timestamp": "2026-01-15T10:30:00Z"}'

What It Does:

Validates the JSON data
Adds metadata fields (id, version, created_at, hash, signature)
Writes the document to disk as <collection>/<id>.json
Updates indices
Logs the operation to the WAL

Retrieve a Document

Retrieves a document from a collection and prints it to stdout.

Usage:

sentinel get --store <STORE_PATH> --collection <COLLECTION_NAME> --id <DOCUMENT_ID>

Required Arguments:

-s, --store <STORE_PATH>: Path to the store directory
-c, --collection <COLLECTION_NAME>: Name of the collection
-i, --id <DOCUMENT_ID>: Document identifier

Examples:

# Get a document
sentinel get \
  --store /data/my-store \
  --collection users \
  --id user-123

# Save to a file
sentinel get \
  --store /data/my-store \
  --collection users \
  --id user-123 > user-123.json

# Pretty-print with jq
sentinel get \
  --store /data/my-store \
  --collection users \
  --id user-123 | jq .

What It Does:

Reads the document file from disk
Verifies the document hash for integrity
Optionally verifies the signature
Prints the document JSON to stdout

Update a Document

Updates an existing document in a collection. The entire document is replaced with the new data.

Usage:

sentinel update --store <STORE_PATH> --collection <COLLECTION_NAME> --id <DOCUMENT_ID> --data <JSON_DATA>

Required Arguments:

-s, --store <STORE_PATH>: Path to the store directory
-c, --collection <COLLECTION_NAME>: Name of the collection
-i, --id <DOCUMENT_ID>: Document identifier
-d, --data <JSON_DATA>: New JSON data for the document

Examples:

# Update a document
sentinel update \
  --store /data/my-store \
  --collection users \
  --id user-123 \
  --data '{"name": "Alice Smith", "email": "[email protected]"}'

# Update from a file
sentinel update \
  --store /data/my-store \
  --collection users \
  --id user-123 \
  --data "$(cat updated-user.json)"

# Incremental update with jq
CURRENT=$(sentinel get --store /data/my-store --collection users --id user-123)
UPDATED=$(echo "$CURRENT" | jq '.email = "[email protected]"')
sentinel update \
  --store /data/my-store \
  --collection users \
  --id user-123 \
  --data "$UPDATED"

What It Does:

Validates the new JSON data
Updates metadata (version, updated_at, hash, signature)
Replaces the document file on disk
Updates indices
Logs the operation to the WAL

Delete a Document

Deletes a document from a collection (soft delete by default).

Usage:

sentinel delete --store <STORE_PATH> --collection <COLLECTION_NAME> --id <DOCUMENT_ID>

Required Arguments:

-s, --store <STORE_PATH>: Path to the store directory
-c, --collection <COLLECTION_NAME>: Name of the collection
-i, --id <DOCUMENT_ID>: Document identifier

Examples:

# Delete a document
sentinel delete \
  --store /data/my-store \
  --collection users \
  --id user-123

# Delete with verbose logging
sentinel delete -v \
  --store /data/my-store \
  --collection audit_logs \
  --id audit-2025-12-31

What It Does:

Moves the document to the .deleted/ subdirectory (soft delete)
Updates indices
Logs the operation to the WAL
The document can still be accessed for audit purposes

Note: Sentinel uses soft deletes by default for audit compliance. The document is moved to a .deleted/ directory within the collection but remains accessible.

Complete Workflow Examples

Setting Up a New Store

# Generate keys
SIGNING_KEY=$(sentinel gen key signing)
ENCRYPTION_KEY=$(sentinel gen key encryption)

# Initialize the store
sentinel init \
  --path /data/my-store \
  --signing-key $SIGNING_KEY \
  --passphrase "my-secure-passphrase" \
  --encryption-algorithm xchacha20poly1305

# Create collections
sentinel create-collection --store /data/my-store --name users
sentinel create-collection --store /data/my-store --name audit_logs
sentinel create-collection --store /data/my-store --name certificates

Managing Documents

# Insert documents
sentinel insert \
  --store /data/my-store \
  --collection users \
  --id user-001 \
  --data '{"name": "Alice", "role": "admin"}'

sentinel insert \
  --store /data/my-store \
  --collection users \
  --id user-002 \
  --data '{"name": "Bob", "role": "user"}'

# Retrieve and modify
USER=$(sentinel get --store /data/my-store --collection users --id user-001)
MODIFIED=$(echo "$USER" | jq '.role = "superadmin"')
sentinel update \
  --store /data/my-store \
  --collection users \
  --id user-001 \
  --data "$MODIFIED"

# Delete
sentinel delete --store /data/my-store --collection users --id user-002

Audit Trail Operations

# Create audit log entries
sentinel insert \
  --store /data/my-store \
  --collection audit_logs \
  --id "$(date +%Y%m%d-%H%M%S)-login" \
  --data "{\"action\": \"login\", \"user\": \"alice\", \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"

# View all audit logs (using filesystem tools)
ls -la /data/my-store/audit_logs/

# Search audit logs with grep
grep -r "alice" /data/my-store/audit_logs/

Algorithm Configuration Examples

# High-security configuration
sentinel init \
  --path /data/high-security-store \
  --hash-algorithm blake3 \
  --signature-algorithm ed25519 \
  --encryption-algorithm xchacha20poly1305 \
  --key-derivation-algorithm argon2id

# Constrained environment configuration
sentinel init \
  --path /data/embedded-store \
  --hash-algorithm blake3 \
  --signature-algorithm ed25519 \
  --encryption-algorithm ascon128 \
  --key-derivation-algorithm pbkdf2

Initialize a Store

Generate Cryptographic Keys

Generate a Cryptographic Key

Create a Collection

Insert a Document

Retrieve a Document

Update a Document

Delete a Document

Complete Workflow Examples

Setting Up a New Store

Managing Documents

Audit Trail Operations

Algorithm Configuration Examples

See Also

Related Pages