Setup & Authentication

1. Bootstrap Your First API Key

The first time you use ZiaGit, you need to create an admin API key using the bootstrap endpoint:

export ZIAGIT_API_ENDPOINT="https://git.ziacode.com"

tsx ~/Code/ZiaGit/ziagit-cli.ts bootstrap

2. Configure Environment Variables

Set up your environment to use ZiaGit:

export ZIAGIT_API_KEY="zg_your_api_key_here"
export ZIAGIT_AUTHOR="Your Name"
export ZIAGIT_EMAIL="your@email.com"
export ZIAGIT_API_ENDPOINT="https://git.ziacode.com"

3. Make It Permanent (Optional)

Add these variables to your shell profile:

echo 'export ZIAGIT_API_KEY="zg_your_key"' >> ~/.zshrc
echo 'export ZIAGIT_AUTHOR="Your Name"' >> ~/.zshrc
echo 'export ZIAGIT_EMAIL="your@email.com"' >> ~/.zshrc
echo 'export ZIAGIT_API_ENDPOINT="https://git.ziacode.com"' >> ~/.zshrc

source ~/.zshrc

Quick Start

Create Your First Repository

tsx ~/Code/ZiaGit/ziagit-cli.ts init my-project

cd ~/Code/MyProjects/my-project

echo "# My Project" > README.md
mkdir src
echo "console.log('Hello ZiaGit');" > src/index.js

tsx ~/Code/ZiaGit/ziagit-cli.ts commit my-project main

tsx ~/Code/ZiaGit/ziagit-cli.ts log my-project main

Architecture

System Overview

ZiaGit uses a git-inspired architecture with content-addressable storage:

Git Objects

Storage Model

Directory Structure

repos/
├── {repo-name}/
│   ├── meta.json              # Repository metadata
│   ├── objects/
│   │   └── {sha256-hash}      # Git objects (blobs, trees, commits)
│   └── refs/
│       └── heads/
│           └── {branch-name}  # Branch pointers
└── auth/
    └── keys/
        └── {key-id}.json      # API keys (hashed)

Object Storage

All content is stored using SHA-256 content addressing:

• Immutable: Objects never change once created
• Deduplicated: Identical content stored once
• Verifiable: Content integrity guaranteed by hash

Cost Estimates

Security

API Key Security

• Cryptographically Secure: 256-bit random keys using Web Crypto API
• SHA-256 Hashing: Keys hashed before storage, never stored in plaintext
• Bearer Token Auth: Industry-standard authentication method
• One-Time Bootstrap: Initial admin key creation is protected

Permission Scopes

Best Practices

API Key Management

Create API Key

tsx ~/Code/ZiaGit/ziagit-cli.ts key:create "My App" write

Permissions: read | write | admin

List API Keys

tsx ~/Code/ZiaGit/ziagit-cli.ts key:list

Revoke API Key

tsx ~/Code/ZiaGit/ziagit-cli.ts key:revoke KEY_ID

Repository Commands

Initialize Repository

tsx ~/Code/ZiaGit/ziagit-cli.ts init <repo-name>

Creates a new repository with a default "main" branch.

List Repositories

tsx ~/Code/ZiaGit/ziagit-cli.ts repos

Commit Changes

tsx ~/Code/ZiaGit/ziagit-cli.ts commit <repo-name> <branch>

Commits all changes in the current directory. You'll be prompted for a commit message.

View Commit History

tsx ~/Code/ZiaGit/ziagit-cli.ts log <repo-name> <branch>

Show Commit Details

tsx ~/Code/ZiaGit/ziagit-cli.ts show <repo-name> <commit-hash>

View File Contents

tsx ~/Code/ZiaGit/ziagit-cli.ts cat <repo-name> <commit-hash> <file-path>

Branch Commands

List Branches

tsx ~/Code/ZiaGit/ziagit-cli.ts branches <repo-name>

Create Branch

tsx ~/Code/ZiaGit/ziagit-cli.ts branch <repo-name> <branch-name> <from-commit>

Creates a new branch from the specified commit hash.

# Get the latest commit hash from main
tsx ~/Code/ZiaGit/ziagit-cli.ts log my-project main

# Create new branch from that commit
tsx ~/Code/ZiaGit/ziagit-cli.ts branch my-project feature/new-ui abc123def456

Commit Operations

Creating a Commit

When you commit, ZiaGit:

1. Scans all files in the current directory
2. Creates blob objects for each file
3. Builds a tree structure representing directories
4. Creates a commit object with metadata
5. Updates the branch reference

Commit Message Format

feat: Add new user authentication
fix: Resolve memory leak in parser
docs: Update API documentation
refactor: Simplify database queries

What Gets Committed

ZiaGit automatically excludes common patterns:

• node_modules/
• .git/
• dist/, build/
• .DS_Store
• Hidden files (.env, etc.)

REST API

Base URL: https://git.ziacode.com

Repository Endpoints

Initialize a new repository

List all repositories

Create a new commit

Get commit history for a branch

Get commit details

Branch Endpoints

List all branches

Create a new branch

Example: Create Commit via API

curl -X POST https://git.ziacode.com/repos/my-project/commits \
  -H "Authorization: Bearer zg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "message": "Initial commit",
    "author": {
      "name": "Your Name",
      "email": "your@email.com"
    },
    "files": {
      "README.md": "# My Project",
      "src/index.js": "console.log(\"Hello\");"
    }
  }'

Authentication

Bearer Token Authentication

All API requests (except bootstrap) require authentication via Bearer token:

Authorization: Bearer zg_your_api_key_here

Example Requests

curl -H "Authorization: Bearer $ZIAGIT_API_KEY" \
  https://git.ziacode.com/repos

curl -H "Authorization: Bearer $ZIAGIT_API_KEY" \
  https://git.ziacode.com/repos/my-project/history/main

curl -H "Authorization: Bearer $ZIAGIT_API_KEY" \
  https://git.ziacode.com/repos/my-project/commits/abc123/files/src/index.js

Permissions

Permission Hierarchy

Permission Matrix

Claude Slash Commands

All plugins scaffolded with the Local Add-on automatically include ZiaGit slash commands.

Available Commands

# In Claude Code, type:
/git

# Claude will:
# 1. Show all files to be committed
# 2. Ask for commit message
# 3. Commit to ZiaGit
# 4. Show commit hash

/status

/deploy

/test

/release

WordPress Plugin Integration

CLAUDE.MD Configuration

Each WordPress plugin includes a CLAUDE.MD file with ZiaGit integration instructions.

Environment Setup for Plugins

export ZIAGIT_API_KEY="zg_your_key"
export ZIAGIT_AUTHOR="Your Name"
export ZIAGIT_EMAIL="your@email.com"

Plugin Repositories

Current plugins using ZiaGit:

• electrical-intranet-pro - Branch: main
• central-lms-manager - Branch: main
• seo-content-optimizer - Branch: main
• n1-intranet - Branch: main
• home-cleaning-estimator - Branch: main
• test-plugin - Branch: main

Automatic Scaffolding

New plugins created with the Local Add-on automatically include:

• Pre-configured slash commands
• ZiaGit documentation in CLAUDE.MD
• Repository name matching plugin slug
• Development workflow guides