# AXICOV CLI

Axicov CLI is a powerful command-line tool designed to streamline the deployment process for projects in Axicov. It automatically validates your langchain project configuration, processes environment variables, extracts README content, creates optimized zip archives, and deploys everything to your specified API endpoint.

#### What Axicov CLI Does

* **Configuration Validation**: Ensures your project configuration is correct
* **Automated Deployment**: Deploys metadata and project files to Axicov's store
* **Type Safety**: Full TypeScript support with proper type definitions

### Built for Performance

This CLI is optimized for **Bun runtime** but works seamlessly with Node.js, providing fast execution and native TypeScript support.

***

## Getting Started

#### Prerequisites

* **Node.js** 16.0.0 or higher (or **Bun** runtime)
* **npm**, **yarn**, or **bun** package manager
* A project with configuration files

#### Quick Start

```bash
# Install globally
npm install -g @axicov/cli

# Initialize a new project
axicov init my-project

# Deploy your project
axicov deploy -k "your-api-key"
```

***

## Installation

#### Global Installation (Recommended, but look for version upgrades soon)

```bash
# Using npm
npm install -g @axicov/cli

# Using yarn  
yarn global add @axicov/cli

# Using bun
bun install -g @axicov/cli
```

#### Local Installation

```bash
# Using npm
npm install @axicov/cli --save-dev

# Using yarn
yarn add @axicov/cli --dev

# Using bun
bun add @axicov/cli --dev
```

#### Verify Installation

```bash
axicov --version
# Output: 1.0.2
```

***

## Project Structure

A typical Axicov-enabled project structure looks like this:

```
my-project/
├── axicov.config.ts        # Configuration file (required)
├── README.md               # Project documentation
├── .env                    # Environment variables
├── .gitignore             # Git ignore patterns
├── package.json           # Node.js dependencies
├── src/                   # Source code
│   ├── index.ts
│   └── utils/
├── dist/                  # Build output (auto-created)
│   └── project.zip        # Generated zip file
└── node_modules/          # Dependencies (ignored)
```

#### Key Files

| File               | Purpose                         | Required    |
| ------------------ | ------------------------------- | ----------- |
| `axicov.config.ts` | Main configuration file         | ✅ Yes       |
| `README.md`        | Project documentation           | ✅ Yes       |
| `.env`             | Environment variables           | ✅ Yes       |
| `.gitignore`       | Files to exclude from uploading | Recommended |

***

## Configuration

#### Configuration File

Axicov requires an `axicov.config.ts` (or `axicov.config.js`) file in your project root. This file defines your project metadata and deployment settings.

**Basic Configuration**

```typescript
// axicov.config.ts
const axicovConfig = {
  name: "my-axicov-project",
  description: "A modern TypeScript application with best practices",
  readmePath: "./README.md",
  env: "./.env",
  
  params: {
    version: {
      type: String,
      description: "Project version",
      required: true
    },
    author: {
      type: String,
      description: "Project author",
      required: false
    },
    license: {
      type: String,
      description: "Project license",
      required: false
    }
  },
  
  port: 3000,
  tags: ["TypeScript", "Node.js", "Web Application"]
};

export default axicovConfig;
```

**LangChain TypeScript Configuration**

```typescript
// axicov.config.ts for LangChain projects
const axicovConfig = {
  name: "langchain-ai-app",
  description: "A LangChain TypeScript application for building AI-powered solutions",
  readmePath: "./README.md",
  env: "./.env",
  
  params: {
    prompt: {
      type: String,
      description: "The prompt that the LLM will respond to",
      required: false
    },
    temperature: {
      type: Number,
      description: "LLM temperature setting (0.0 to 1.0)",
      required: false
    },
    maxTokens: {
      type: Number,
      description: "Maximum tokens for LLM responses",
      required: false
    }
  },
  
  port: 3000,
  tags: ["LangChain", "TypeScript", "AI", "LLM", "Vector Store"]
};

export default axicovConfig;
```

#### Configuration Fields

| Field         | Type       | Required | Description                                |
| ------------- | ---------- | -------- | ------------------------------------------ |
| `name`        | `string`   | Yes      | Project name (must be non-empty)           |
| `description` | `string`   | Yes      | Project description                        |
| `readmePath`  | `string`   | Yes      | Path to README file (relative or absolute) |
| `env`         | `string`   | Yes      | Path to environment file                   |
| `params`      | `object`   | Yes      | Custom parameters with type definitions    |
| `port`        | `number`   | Yes      | Application port (1-65535)                 |
| `tags`        | `string[]` | No       | Optional array of project tags             |

#### Parameter Definitions

Each parameter in the `params` object must follow this structure:

```typescript
{
  type: String | Number,        // Constructor function
  description: string,          // Human-readable description
  required: boolean            // Whether the parameter is required
}
```

#### Environment Variables

Create a `.env` file in your project root:

```bash
# .env
NODE_ENV=production
API_URL=https://api.example.com
DATABASE_URL=postgresql://localhost:5432/mydb
SECRET_KEY=your-secret-key-here

# LangChain specific (if applicable)
OPENAI_API_KEY=sk-...
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=ls__...
```

***

## Troubleshooting

#### Common Issues and Solutions

**1. Configuration File Not Found**

**Error:**

```bash
Configuration file not found. Looking for: axicov.config.ts or axicov.config.js in /path/to/project
```

**Solutions:**

* Run `axicov init` to create the configuration file
* Ensure you're in the correct project directory
* Check file naming: must be exactly `axicov.config.ts` or `axicov.config.js`

**2. Invalid Configuration Structure**

**Error:**

```bash
Configuration validation failed
   • 'params' must be an object, got array
   • params.version.type must be String or Number constructor
```

**Solutions:**

* Verify parameter definitions follow the correct structure:

  ```typescript
  params: {  fieldName: {    type: String,           // Must be String or Number constructor    description: string,    // Must be a string    required: boolean      // Must be true or false  }}
  ```
* Check that all required fields are present and have correct types

**3. Environment File Issues**

**Error:**

```bash
Environment file not found: /path/to/.env
```

**Solutions:**

* Create the `.env` file: `touch .env`
* Check the path in your config file matches the actual file location
* Ensure proper file permissions (readable)

**Environment parsing errors:**

```bash
Warning: Invalid env line 5 in .env: "INVALID_LINE_WITHOUT_EQUALS"
```

**Solutions:**

* Each line should follow format: `KEY=value`
* Use `#` for comments
* Quote values with spaces: `KEY="value with spaces"`

**4. Port Configuration Issues**

**Error:**

```bash
'port' must be between 1 and 65535, got 70000
```

**Solutions:**

* Choose a port in valid range: 1-65535
* Recommended: Use ports > 1024 to avoid system port conflicts
* Common choices: 3000, 8080, 8000, 5000

**5. API Deployment Failures**

**Error:**

```bash
API request failed: 401 Unauthorized
Response: {"error": "Invalid API key"}
```

**Solutions:**

* Verify your API key is correct and active
* Check if the API key has proper permissions
* Ensure you're using the correct API endpoint

**Error:**

```bash
Failed to deploy: fetch failed
```

**Solutions:**

* Check internet connectivity
* Verify the API endpoint is accessible
* Ensure no firewall blocking outbound requests

**6. File Permission Issues**

**Error:**

```bash
Output directory is not writable: /path/to/dist
```

**Solutions:**

* Create the directory: `mkdir -p dist`
* Fix permissions: `chmod 755 dist`
* Use a different output path: `-o "./build"`

**7. Large Project Zipping Issues**

**Error:**

```bash
Archive size: 150.2 MB
Warning: Large archive may cause deployment issues
```

**Solutions:**

* Review your `.gitignore` to exclude unnecessary files:

  ```gitignore
  node_modules/dist/*.log.DS_Storecoverage/
  ```
* Remove large files that aren't needed for deployment
* Consider using compression level 9: modify source code or use custom build

#### 8. Configuration validation error

You can get a message like this:

```
Configuration validation failed
   • Failed to load configuration: Error loading config file: Failed to load config file. ES module error: Unexpected token 'export'. CommonJS error: Unexpected token 'export'
✖ Deployment failed
```

#### to fix this, change this line in axicov.config.ts&#x20;

```
export default axicovConfig
```

to,

```
module.exports = axicovConfig;
```

#### Debug Mode

Enable verbose output for detailed troubleshooting:

```bash
axicov deploy -k "your-key" -v
```

This shows:

* Full configuration details
* Complete metadata JSON
* File scanning progress
* API request/response details

#### Getting Help

If you encounter issues not covered here:

1. **Check the documentation** in your project's README
2. **Verify all requirements** are met (Node.js version, file structure)
3. **Test with a minimal project** to isolate the issue
4. **Check API endpoint status** if deployment fails

***

## Best Practices

#### 1. Project Organization

**Recommended Structure:**

```
your-project/
├── axicov.config.ts          # Keep config in TypeScript
├── README.md                 # Comprehensive documentation
├── .env                      # Production environment
├── .env.example              # Template for other developers
├── .gitignore               # Properly configured
├── src/                     # Source code
├── tests/                   # Test files
└── docs/                    # Additional documentation
```

#### 2. Configuration Management

**Type-Safe Configurations:**

```typescript
// Use TypeScript for better IDE support and validation
const axicovConfig = {
  // Use descriptive names
  name: "user-authentication-service",
  
  // Write clear descriptions
  description: "Handles user registration, login, and JWT token management",
  
  // Use consistent paths
  readmePath: "./README.md",
  env: "./.env",
  
  // Document parameters thoroughly
  params: {
    jwtSecret: {
      type: String,
      description: "Secret key for JWT token signing and verification",
      required: true
    },
    tokenExpiry: {
      type: String,
      description: "JWT token expiration time (e.g., '7d', '24h')",
      required: false
    }
  }
};
```

#### 3. Environment Variables

**Security Best Practices:**

```bash
# .env - Production values
NODE_ENV=production
JWT_SECRET=your-super-secret-production-key
DATABASE_URL=postgresql://user:password@prod-db:5432/app

# Don't commit sensitive values!
# Use .env.example for templates
```

```bash
# .env.example - Template for developers
NODE_ENV=development
JWT_SECRET=development-secret-change-in-production
DATABASE_URL=postgresql://localhost:5432/app_dev
```

**Organization:**

```bash
# Group related variables
# === Database Configuration ===
DATABASE_URL=postgresql://localhost:5432/myapp
DATABASE_POOL_SIZE=10
DATABASE_TIMEOUT=30000

# === Authentication ===
JWT_SECRET=your-jwt-secret
JWT_EXPIRY=7d
BCRYPT_ROUNDS=12

# === External APIs ===
OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_...
SENDGRID_API_KEY=SG...
```

#### 4. README Documentation

**Structure your README.md:**

````markdown
# Project Name

Brief description of what your project does.

## Features

- Feature 1
- Feature 2

## Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `JWT_SECRET` | JWT signing secret | Yes | - |
| `PORT` | Server port | No | `3000` |

## Deployment

This project uses Axicov CLI for deployment:

```bash
axicov deploy -k "your-api-key"
````

***

*This guide covers the essential functionality of Axicov CLI. For advanced use cases and API integration details, refer to the official documentation or source code.*
