Installation

Get ZGI installed and ready to use in minutes.

System Requirements

Before installing ZGI, ensure you have:

Node.js: 16.0 or higher
npm: 7.0 or higher (or yarn 1.22+)
Git: 2.0 or higher
Disk Space: At least 500MB free

Optional Requirements

Python: 3.8+ (for some integrations)
Docker: 20.0+ (for containerized deployment)
PostgreSQL: 12+ (for local database)

Installation Methods

Method 1: NPM (Recommended)

Install ZGI CLI globally:

npm install -g @zgi/cli

Verify installation:

zgi --version

Method 2: Yarn

yarn global add @zgi/cli

Verify installation:

zgi --version

Method 3: From Source

Clone the repository and build:

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

Method 4: Docker

Pull the Docker image:

docker pull zgi/cli:latest

Run ZGI in Docker:

docker run -it zgi/cli:latest zgi --version

Quick Setup

1. Create a New Project

zgi init my-first-project
cd my-first-project

This creates a new ZGI project with:

Basic project structure
Example agent
Configuration files
Package dependencies

2. Install Dependencies

npm install

3. Configure Environment

Create a .env file:

cp .env.example .env

Edit .env with your settings:

# API Configuration
ZGI_API_KEY=your-api-key
ZGI_API_URL=https://api.zgi.ai

# Model Configuration
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

# Database Configuration (Optional)
DATABASE_URL=postgresql://user:password@localhost:5432/zgi_db

# Logging
LOG_LEVEL=info

4. Start Development Server

npm run dev

Your ZGI project is now running!

Configuration

Project Structure

my-first-project/
├── src/
│   ├── agents/
│   │   └── example.ts
│   ├── tools/
│   │   └── example.ts
│   └── index.ts
├── .env
├── .env.example
├── package.json
├── tsconfig.json
└── zgi.config.json

zgi.config.json

Configure your ZGI project:

{
  "name": "my-first-project",
  "version": "1.0.0",
  "description": "My first ZGI project",
  "agents": {
    "defaultModel": "gpt-4",
    "timeout": 30000
  },
  "database": {
    "type": "postgresql",
    "host": "localhost",
    "port": 5432
  },
  "plugins": {
    "enabled": true,
    "directory": "./plugins"
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}

Environment Variables

Required Variables

| Variable | Description | Example | |----------|-------------|---------| | ZGI_API_KEY | Your ZGI API key | zgi_sk_... | | OPENAI_API_KEY | OpenAI API key (if using OpenAI) | sk_... |

Optional Variables

| Variable | Description | Default | |----------|-------------|---------| | ZGI_API_URL | ZGI API endpoint | https://api.zgi.ai | | LOG_LEVEL | Logging level | info | | DATABASE_URL | Database connection string | - | | NODE_ENV | Environment | development |

Verify Installation

Test Your Setup

# Create a test agent
zgi create agent test-agent

# Run the agent
npm run dev

# In another terminal, test the agent
curl http://localhost:3000/agents/test-agent

Check Connectivity

# Test API connection
zgi status

# List available models
zgi models list

# Check your account
zgi account info

Troubleshooting

Issue: Command not found

Solution: Ensure npm global bin is in your PATH:

# Check npm global bin
npm config get prefix

# Add to PATH (macOS/Linux)
export PATH="$(npm config get prefix)/bin:$PATH"

# Add to PATH (Windows)
# Add %APPDATA%\npm to your PATH environment variable

Issue: Permission denied

Solution: Use sudo or fix npm permissions:

# Option 1: Use sudo
sudo npm install -g @zgi/cli

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Issue: API key not recognized

Solution: Verify your API key:

# Check if API key is set
echo $ZGI_API_KEY

# Set API key
export ZGI_API_KEY=your-api-key

# Test connection
zgi status

Issue: Port already in use

Solution: Use a different port:

# Run on different port
npm run dev -- --port 3001

Next Steps

Quick Start - Create your first agent
Guides - Learn about each module
API Reference - Explore the API
Examples - See real-world examples

Getting Help

Uninstall

To uninstall ZGI:

npm uninstall -g @zgi/cli

Or with Yarn:

yarn global remove @zgi/cli