CodeQuill CLI

Secure snapshots, authorship, and code preservation

Command-line interface for CodeQuill, memory infrastructure for software. Create snapshots, claim repositories, publish releases, attest artifacts, and preserve source code with zero-custody encryption.

Installation

From npm

npm install -g codequill

From source

git clone https://github.com/codequill/codequill-cli.git
cd codequill-cli
npm install
npm run build
npm link

Requirements

• Node.js 18+
• Git (for repository detection)

Quick Start

# Authenticate with CodeQuill
codequill login

# Claim authorship of current repository
codequill claim

# Create a snapshot of your latest commit
codequill snapshot

# Publish a release
codequill publish

# Create an encrypted preservation (defaults to the latest published snapshot)
codequill preserve [snapshot-id]

Commands

Authentication

codequill login

Authenticate via device-code flow. Opens your browser to authorize the CLI.

codequill login

codequill who

Show the current authenticated user.

codequill who

codequill quota

Display your subscription plan and usage:

• Claimed repositories
• Snapshots created
• Preservations stored
• Attestations made

codequill quota

Repository Management

codequill claim

Claim authorship of a repository on-chain.

# Auto-detect from current git repository
codequill claim

# Skip confirmation prompt
codequill claim --no-confirm

Options:

• --no-confirm - Skip interactive confirmation
• --confirmations <n> - Wait for N confirmations (default: 1)
• --timeout <ms> - Timeout for confirmation
• --no-wait - Submit transaction and return immediately
• --json - Output in JSON format

codequill status

Show repository status and recent snapshots.

codequill status

codequill log

View snapshot history for the current repository.

codequill log

Snapshots

codequill snapshot

Create a deterministic snapshot (Merkle tree) of the repository at a specific commit.

# Snapshot current HEAD
codequill snapshot

# Snapshot specific commit
codequill snapshot --commit abc123

# Custom concurrency
codequill snapshot --concurrency 16

Options:

• --commit <hash> - Commit hash to snapshot (default: HEAD)
• --concurrency <n> - Number of concurrent file reads (default: 8)
• --salt <hex> - Custom salt for path hashing (64 hex chars)
• --print-salt - Display the salt in output

codequill pull

Download all published snapshot manifests for the current repository.

codequill pull

Manifests are stored in .codequill/snapshots/.

Publishing

codequill publish

Publish a snapshot by anchoring its Merkle root on-chain and storing the manifest on IPFS.

# Publish latest snapshot
codequill publish

# Publish specific commit
codequill publish <commit-hash>

Options:

• --no-confirm - Skip confirmation prompt
• --confirmations <n> - Wait for N confirmations (default: 1)
• --timeout <ms> - Timeout for confirmation
• --no-wait - Submit and return immediately
• --json - Output in JSON format

Note: Releases (named, governed versions) are created in the web app at app.codequill.xyz. The CLI publishes snapshots.

codequill wait

Wait for a transaction to confirm.

codequill wait <tx-hash>

Attestations

codequill attest

Create an attestation linking a build artifact to a published release.

codequill attest <artifact> <release-id>

Arguments:

• <artifact> - Path to the build artifact
• <release-id> - Release ID to attest against

Options:

• --subject-name <name> - Artifact name
• --subject-version <ver> - Artifact version
• --upstream <purl> - Upstream dependency (repeatable)
• --no-confirm - Skip confirmation
• --confirmations <n> - Wait for N confirmations
• --json - Output in JSON format

Note: Attestations require an accepted release. The release must pass governance approval before attestation.

codequill verify-attestation

Check a local binary or folder (or a bare digest) against the publisher's on-chain attestation. This calls the public endpoint GET /v1/public/attestations/verify, so it needs network access and no login. It proves provenance and integrity only: that these exact bytes match an attestation a publisher anchored on-chain, and whether that attestation is still active or was revoked. It does not certify that the code is safe, bug-free, or free of malicious behaviour.

# Hash a file or a folder and verify it
codequill verify-attestation ./dist/app
codequill verify-attestation ./dist/

# Verify a precomputed digest without hashing
codequill verify-attestation --digest sha256:<hex>
codequill verify-attestation <64-hex-sha256>

# Machine-readable output for CI
codequill verify-attestation ./dist/app --json

Arguments / options:

• [pathOrDigest] - a filesystem path to hash, or a digest string (sha256:<hex>, image@sha256:<hex>, or bare hex).
• --digest <d> - treat the input as a precomputed digest and skip hashing.
• --algo <algo> - digest algorithm (sha256 default; inferred from a digest string).
• --json - emit a machine-readable result for CI gating.

Fail closed: authenticity requires an authoritative on-chain confirmation. If the chain read cannot be completed, the verdict is unconfirmed (never matched), the command exits non-zero, and it prints an UNVERIFIED warning rather than a green result. Exit code is 0 only for a confirmed, non-revoked match.

JSON keys (camelCase, stable contract): matched (bool), verdict (matched | unconfirmed | revoked | not_found | unsupported_algo | error), onChainConfirmed, revoked, supported, algo, digest, author, releaseId, releaseName, attestationCid, timestamp, txHash, matchesCount, notes. A CI job may gate on either the exit code or .matched.

Proofs

codequill prove

Generate a Merkle proof that a specific file was included in a snapshot.

codequill prove <file> <snapshot-id>

# Include plaintext path in proof
codequill prove <file> <snapshot-id> --disclose

# Custom output path
codequill prove LICENSE <snapshot-id> --out evidence/license-proof.json

Arguments:

• <file> - Path to file to prove inclusion for
• <snapshot-id> - Snapshot ID to prove against

Options:

• --disclose - Include plaintext path in proof (privacy tradeoff)
• --out <file> - Output path for proof file

codequill verify-proof

Verify a proof of inclusion (offline operation).

codequill verify-proof <proof-file>

Preservations

codequill preserve

Create an encrypted preservation (backup) of source code tied to a published snapshot.

codequill preserve [snapshot-id]

Arguments:

• [snapshot-id] - Published snapshot ID to preserve. Optional: when omitted, falls back to the latest published snapshot for the current repository (mirrors how publish defaults to HEAD).

Options:

• --no-confirm - Skip confirmation
• --confirmations <n> - Wait for N confirmations
• --timeout <ms> - Timeout for confirmation
• --no-wait - Submit and return immediately
• --json - Output in JSON format

Encryption: Uses AES-256-GCM with passkey-derived keys (zero-custody). CodeQuill never sees plaintext source code.

Learning

codequill why

Learn about CodeQuill concepts.

# Overview
codequill why

# Specific topics
codequill why claim
codequill why snapshot
codequill why publish
codequill why prove
codequill why attest
codequill why preserve

Options:

• --short - Brief explanation
• --ci - CI-friendly explanation

Configuration

API Endpoint

Set the CodeQuill API base URL:

export CODEQUILL_API_BASE_URL=https://api.codequill.xyz

Default: https://api.codequill.xyz

Config Directory

Authentication tokens are stored at ~/.config/codequill/config.json with 0600 permissions.

Override for testing:

export CODEQUILL_CONFIG_DIR=/custom/path

Session Management

• Access tokens auto-refresh using your refresh token
• Refresh tokens valid for ~30 days
• Run codequill login to re-authenticate when expired

How It Works

The CLI is a lightweight client that communicates with the CodeQuill backend:

1. Snapshots - Created locally by hashing files and building a Merkle tree. No source code is uploaded.
2. Privacy - File paths are salted before hashing (passkey-derived salt). Enables selective disclosure.
3. Publishing - Anchors snapshot Merkle roots on Ethereum and stores manifests on IPFS.
4. Releases - Created in the web app. Named, governed versions that group snapshots and enable attestations.
5. Attestations - Links build artifacts to accepted releases. Records who, what, and when on-chain.
6. Preservations - Encrypts full source archives client-side. Zero-custody (passkey-derived encryption).
7. Proofs - Merkle proofs of file inclusion. Verifiable by anyone, created with authority.

Architecture

• CLI - Evidence production (snapshots, attestations, proofs)
• Web App - Configuration and governance (app.codequill.xyz)
• Smart Contracts - Immutable on-chain records (Ethereum)
• IPFS - Decentralized storage (manifests, preservations)

Even if CodeQuill servers are compromised, the evidence layer remains independently verifiable.

Development

Build

npm run build

Watch mode

npm run dev

Testing

npm test
npm run test:watch
npm run coverage

Documentation

Full documentation: docs.codequill.xyz

License

MIT © CodeQuill