Skip to content

CLI.md

Latest commit

 

History

History
303 lines (214 loc) · 7.41 KB

CLI.md

File metadata and controls

303 lines (214 loc) · 7.41 KB

DXT CLI Documentation

The DXT CLI provides tools for building Desktop Extensions.

Installation

npm install -g @anthropic-ai/dxt
Usage: dxt [options] [command]

Tools for building Desktop Extensions

Options:
  -V, --version              output the version number
  -h, --help                 display help for command

Commands:
  init [directory]           Create a new DXT extension manifest
  validate <manifest>        Validate a DXT manifest file
  pack <directory> [output]  Pack a directory into a DXT extension
  sign [options] <dxt-file>  Sign a DXT extension file
  verify <dxt-file>          Verify the signature of a DXT extension file
  info <dxt-file>            Display information about a DXT extension file
  unsign <dxt-file>          Remove signature from a DXT extension file
  help [command]             display help for command

Commands

dxt init [directory]

Creates a new DXT extension manifest interactively.

# Initialize in current directory
dxt init

# Initialize in a specific directory
dxt init my-extension/

The command will prompt you for:

  • Extension name (defaults from package.json or folder name)
  • Author name (defaults from package.json)
  • Extension ID (auto-generated from author and extension name)
  • Display name
  • Version (defaults from package.json or 1.0.0)
  • Description
  • Author email and URL (optional)
  • Server type (Node.js, Python, or Binary)
  • Entry point (with sensible defaults per server type)
  • Tools configuration
  • Keywords, license, and repository information

After creating the manifest, it provides helpful next steps based on your server type.

dxt validate <path>

Validates a DXT manifest file against the schema. You can provide either a direct path to a manifest.json file or a directory containing one.

# Validate specific manifest file
dxt validate manifest.json

# Validate manifest in directory
dxt validate ./my-extension
dxt validate .

dxt pack <directory> [output]

Packs a directory into a DXT extension file.

# Pack current directory into extension.dxt
dxt pack .

# Pack with custom output filename
dxt pack my-extension/ my-extension-v1.0.dxt

The command automatically:

  • Validates the manifest.json
  • Excludes common development files (.git, node_modules/.cache, .DS_Store, etc.)
  • Creates a compressed .dxt file (ZIP with maximum compression)

dxt sign <dxt-file>

Signs a DXT extension file with a certificate.

# Sign with default certificate paths
dxt sign my-extension.dxt

# Sign with custom certificate and key
dxt sign my-extension.dxt --cert /path/to/cert.pem --key /path/to/key.pem

# Sign with intermediate certificates
dxt sign my-extension.dxt --cert cert.pem --key key.pem --intermediate intermediate1.pem intermediate2.pem

# Create and use a self-signed certificate
dxt sign my-extension.dxt --self-signed

Options:

  • --cert, -c: Path to certificate file (PEM format, default: cert.pem)
  • --key, -k: Path to private key file (PEM format, default: key.pem)
  • --intermediate, -i: Paths to intermediate certificate files
  • --self-signed: Create a self-signed certificate if none exists

dxt verify <dxt-file>

Verifies the signature of a signed DXT extension file.

dxt verify my-extension.dxt

Output includes:

  • Signature validity status
  • Certificate subject and issuer
  • Certificate validity dates
  • Certificate fingerprint
  • Warning if self-signed

dxt info <dxt-file>

Displays information about a DXT extension file.

dxt info my-extension.dxt

Shows:

  • File size
  • Signature status
  • Certificate details (if signed)

dxt unsign <dxt-file>

Removes the signature from a DXT extension file (for development/testing).

dxt unsign my-extension.dxt

Certificate Requirements

For signing extensions, you need:

  1. Certificate: X.509 certificate in PEM format

    • Should have Code Signing extended key usage
    • Can be self-signed (for development) or CA-issued (for production)

  2. Private Key: Corresponding private key in PEM format

    • Must match the certificate's public key

  3. Intermediate Certificates (optional): For CA-issued certificates

    • Required for proper certificate chain validation

Example Workflows

Quick Start with Init

# 1. Create a new extension directory
mkdir my-awesome-extension
cd my-awesome-extension

# 2. Initialize the extension
dxt init

# 3. Follow the prompts to configure your extension
# The tool will create a manifest.json with all necessary fields

# 4. Create your server implementation based on the entry point you specified

# 5. Pack the extension
dxt pack .

# 6. (Optional) Sign the extension
dxt sign my-awesome-extension.dxt --self-signed

Development Workflow

# 1. Create your extension
mkdir my-extension
cd my-extension

# 2. Initialize with dxt init or create manifest.json manually
dxt init

# 3. Implement your server
# For Node.js: create server/index.js
# For Python: create server/main.py
# For Binary: add your executable

# 4. Validate manifest
dxt validate manifest.json

# 5. Pack extension
dxt pack . my-extension.dxt

# 6. (Optional) Sign for testing
dxt sign my-extension.dxt --self-signed

# 7. Verify signature
dxt verify my-extension.dxt

# 8. Check extension info
dxt info my-extension.dxt

Production Workflow

# 1. Pack your extension
dxt pack my-extension/

# 2. Sign with production certificate
dxt sign my-extension.dxt \
  --cert production-cert.pem \
  --key production-key.pem \
  --intermediate intermediate-ca.pem root-ca.pem

# 3. Verify before distribution
dxt verify my-extension.dxt

Excluded Files

When packing an extension, the following files/patterns are automatically excluded:

  • .DS_Store, Thumbs.db
  • .gitignore, .git/
  • *.log, npm-debug.log*, yarn-debug.log*, yarn-error.log*
  • .npm/, .npmrc, .yarnrc, .yarn/, .pnp.*
  • node_modules/.cache/, node_modules/.bin/
  • *.map
  • .env.local, .env.*.local
  • package-lock.json, yarn.lock

Custom Exclusions with .dxtignore

You can create a .dxtignore file in your extension directory to specify additional files and patterns to exclude during packing. This works similar to .npmignore or .gitignore:

# .dxtignore example
# Comments start with #
*.test.js
src/**/*.test.ts
coverage/
*.log
.env*
temp/
docs/

The .dxtignore file supports:

  • Exact matches: filename.txt
  • Simple globs: *.log, temp/*
  • Directory paths: docs/, coverage/
  • Comments: Lines starting with # are ignored
  • Empty lines: Blank lines are ignored

When a .dxtignore file is found, the CLI will display the number of additional patterns being applied. These patterns are combined with the default exclusion list.

Technical Details

Signature Format

DXT uses PKCS#7 (Cryptographic Message Syntax) for digital signatures:

  • Signatures are stored in DER-encoded PKCS#7 SignedData format
  • The signature is appended to the DXT file with markers (DXT_SIG_V1 and DXT_SIG_END)
  • The entire DXT content (excluding the signature block) is signed
  • Detached signature format - the original ZIP content remains unmodified

Signature Structure

[Original DXT ZIP content]
DXT_SIG_V1
[Base64-encoded PKCS#7 signature]
DXT_SIG_END

This approach allows:

  • Backward compatibility (unsigned DXT files are valid ZIP files)
  • Easy signature verification and removal
  • Support for certificate chains with intermediate certificates