CLI Command Reference

This page provides a comprehensive reference for all JACS command-line interface commands.

Global Commands

jacs version

Prints version and build information for the JACS installation.

jacs version

jacs init

Initialize JACS by creating both configuration and agent (with cryptographic keys). This is typically the first command run when setting up JACS.

jacs init

jacs help

Print help information for JACS commands.

jacs help [COMMAND]

Configuration Commands

jacs config

Work with JACS configuration settings.

jacs config [SUBCOMMAND]

Note: Specific subcommands for config are not detailed in the current help output.

Agent Commands

jacs agent

Work with JACS agents - the cryptographic identities that sign and verify documents.

jacs agent [SUBCOMMAND]

Note: Specific subcommands for agent management are not detailed in the current help output.

Task Commands

jacs task

Work with JACS agent tasks - structured workflows between agents.

jacs task [SUBCOMMAND]

Note: Specific subcommands for task management are not detailed in the current help output.

Document Commands

The jacs document command provides comprehensive document management capabilities.

jacs document create

Create a new JACS document, either by embedding or parsing a document with optional file attachments.

Usage:

jacs document create [OPTIONS]

Options:

  • -a <agent-file> - Path to the agent file. If not specified, uses config jacs_agent_id_and_version
  • -f <filename> - Path to input file. Must be JSON format
  • -o <output> - Output filename for the created document
  • -d <directory> - Path to directory of files. Files should end with .json
  • -v, --verbose - Enable verbose output
  • -n, --no-save - Instead of saving files, print to stdout
  • -s, --schema <schema> - Path to JSON schema file to use for validation
  • --attach <attach> - Path to file or directory for file attachments
  • -e, --embed <embed> - Embed documents or keep them external [possible values: true, false]
  • -h, --help - Print help information

Examples:

# Create document from JSON file
jacs document create -f my-document.json

# Create document with embedded attachment
jacs document create -f document.json --attach ./image.jpg --embed true

# Create document with referenced attachment
jacs document create -f document.json --attach ./data.csv --embed false

# Create from directory of JSON files
jacs document create -d ./documents/

# Create with custom schema validation
jacs document create -f document.json -s custom-schema.json

# Print to stdout instead of saving
jacs document create -f document.json --no-save

jacs document update

Create a new version of an existing document. Requires both the original JACS file and the modified JACS metadata.

Usage:

jacs document update [OPTIONS]

Options:

  • -a <agent-file> - Path to the agent file
  • -f <filename> - Path to original document file
  • -n <new-file> - Path to new/modified document file
  • -o <output> - Output filename for updated document
  • -v, --verbose - Enable verbose output
  • -n, --no-save - Print to stdout instead of saving
  • -s, --schema <schema> - Path to JSON schema file for validation
  • --attach <attach> - Path to file or directory for additional attachments
  • -e, --embed <embed> - Embed new attachments or keep them external
  • -h, --help - Print help information

Example:

# Update document with new version
jacs document update -f original.json -n modified.json -o updated.json

# Update and add new attachments
jacs document update -f original.json -n modified.json --attach ./new-file.pdf --embed false

jacs document verify

Verify a document's hash, signatures, and schema compliance.

Usage:

jacs document verify [OPTIONS]

Options:

  • -a <agent-file> - Path to the agent file
  • -f <filename> - Path to input file. Must be JSON format
  • -d <directory> - Path to directory of files. Files should end with .json
  • -v, --verbose - Enable verbose output
  • -s, --schema <schema> - Path to JSON schema file to use for validation
  • -h, --help - Print help information

Examples:

# Verify single document
jacs document verify -f signed-document.json

# Verify all documents in directory
jacs document verify -d ./documents/

# Verify with custom schema
jacs document verify -f document.json -s custom-schema.json

Verification Process:

  1. Hash verification - Confirms document integrity
  2. Signature verification - Validates cryptographic signatures
  3. Schema validation - Ensures document structure compliance
  4. File integrity - Checks SHA256 checksums of attached files

jacs document extract

Extract embedded file contents from documents back to the filesystem.

Usage:

jacs document extract [OPTIONS]

Options:

  • -a <agent-file> - Path to the agent file
  • -f <filename> - Path to input file containing embedded files
  • -d <directory> - Path to directory of files to process
  • -s, --schema <schema> - Path to JSON schema file for validation
  • -h, --help - Print help information

Examples:

# Extract embedded files from single document
jacs document extract -f document-with-embedded-files.json

# Extract from all documents in directory  
jacs document extract -d ./documents/

Extract Process:

  1. Reads embedded file contents from document
  2. Decodes base64-encoded data
  3. Writes files to their original paths
  4. Creates backup of existing files (with timestamp)

Agreement Commands

JACS provides specialized commands for managing multi-agent agreements.

jacs document check-agreement

Given a document, provide a list of agents that should sign the document.

Usage:

jacs document check-agreement [OPTIONS]

jacs document create-agreement

Create an agreement structure for a document that requires multiple agent signatures.

Usage:

jacs document create-agreement [OPTIONS]

jacs document sign-agreement

Sign the agreement section of a document with the current agent's cryptographic signature.

Usage:

jacs document sign-agreement [OPTIONS]

Common Patterns

Basic Document Lifecycle

# 1. Initialize JACS
jacs init

# 2. Create document with attachments
jacs document create -f document.json --attach ./files/ --embed true

# 3. Verify document integrity
jacs document verify -f created-document.json

# 4. Update document if needed
jacs document update -f original.json -n modified.json

# 5. Extract embedded files when needed
jacs document extract -f document.json

Working with Attachments

# Embed small files for portability
jacs document create -f doc.json --attach ./small-image.png --embed true

# Reference large files to save space
jacs document create -f doc.json --attach ./large-video.mp4 --embed false

# Attach multiple files from directory
jacs document create -f doc.json --attach ./attachments/ --embed false

Schema Validation Workflow

# Create with schema validation
jacs document create -f document.json -s schema.json

# Verify against specific schema
jacs document verify -f document.json -s schema.json

Global Options

Most commands support these common options:

  • -h, --help - Show help information
  • -v, --verbose - Enable verbose output for debugging
  • -a <agent-file> - Specify custom agent file (overrides config default)

Exit Codes

  • 0 - Success
  • 1 - General error (invalid arguments, file not found, etc.)
  • 2 - Verification failure (hash mismatch, invalid signature, etc.)
  • 3 - Schema validation failure

Environment Variables

  • JACS_CONFIG_PATH - Override default configuration file location
  • JACS_DATA_DIR - Override default data directory location
  • JACS_AGENT_FILE - Default agent file to use (if not specified with -a)

File Formats

Input Files

  • JSON documents - Must be valid JSON format
  • Schema files - JSON Schema format (draft-07 compatible)
  • Agent files - JACS agent format with cryptographic keys
  • Attachments - Any file type (automatically detected MIME type)

Output Files

  • JACS documents - JSON format with JACS metadata, signatures, and checksums
  • Extracted files - Original format of embedded attachments