Velar CLI

Command-line interface for deploying static sites to Velar.

Installation

Global Installation (Recommended)

npm install -g @camozdevelopment/velar

Local Development

cd cli
npm install
npm run build
npm link

Commands

velar login

Authenticate with Velar and generate an access token.

velar login

The token is saved to ~/.velar/config.json.

Example:

$ velar login
✔ Successfully authenticated!

Token: abc123def4...
Token saved to ~/.velar/config.json

velar deploy

Deploy your static site.

velar deploy [options]

Options:

• -d, --dir <directory> - Specify build output directory
• -n, --name <name> - Custom project name
• --skip-build - Skip the build step

Examples:

Deploy with auto-detection:

$ velar deploy

🚀 Velar Deploy

Project: my-app
Output: dist
Size: 2.5 MB

✔ Package created
✔ Deployment successful!

✓ Deployment Complete

Details:
  Deployment ID: xyz789
  Files: 42
  Total Size: 2.5 MB

🌐 Your site is live at:
  https://my-app.velardev.app

Specify output directory:

velar deploy --dir build

Custom project name:

velar deploy --name my-awesome-app

Skip build step:

velar deploy --skip-build

velar list / velar ls

List all your deployed projects.

velar list

Example:

$ velar list

📦 Your Projects

my-app
  ID: proj_abc123
  Subdomain: my-app
  URL: https://my-app.velardev.app
  Created: 1/1/2024, 12:00:00 PM

portfolio
  ID: proj_def456
  Subdomain: portfolio
  URL: https://portfolio.velardev.app
  Created: 1/2/2024, 3:30:00 PM

velar rollback

Rollback to a previous deployment.

velar rollback <project-id> <deployment-id>

Example:

$ velar rollback proj_abc123 dep_xyz789

✔ Rollback successful!

Deployment dep_xyz789 is now active.

Configuration

The CLI stores configuration in ~/.velar/config.json:

{
  "token": "your-auth-token",
  "apiUrl": "https://velardev.app"
}

Custom API URL

Set a custom API URL:

export VELAR_API_URL=https://api.myvelar.com
velar deploy

Build Detection

The CLI automatically detects your build output directory by looking for:

1. out (Next.js export)
2. dist (Vite, Rollup, Parcel)
3. build (Create React App, Vue CLI)
4. public (Static sites)
5. .next (Next.js)

If no output directory is found, it will attempt to run your build command.

Build Command Detection

Looks for these scripts in package.json:

• build
• prod
• production

Example package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

The CLI will automatically run npm run build.

Project Name

The CLI determines the project name by:

1. Using --name flag if provided
2. Reading name from package.json
3. Using current directory name as fallback

Names are sanitized to be subdomain-safe:

• Lowercase only
• Alphanumeric and hyphens
• No consecutive hyphens

Examples:

• My App → my-app
• my_awesome_project → my-awesome-project
• Hello World!!! → hello-world

File Exclusions

The following patterns are never uploaded:

• node_modules/
• .git/
• .env, .env.local
• .DS_Store, Thumbs.db
• *.log

Only your build output is uploaded, keeping deployments fast and efficient.

Environment Variables

VELAR_API_URL

Override the default API URL.

export VELAR_API_URL=https://staging.velardev.app

Error Handling

"Not authenticated"

Run velar login to generate a new token.

"Could not detect build output directory"

Specify the directory manually:

velar deploy --dir dist

"Build failed"

Your build command failed. Check the output for errors, fix them, and try again.

"Deployment exceeds maximum size"

Your deployment is too large (>100MB). Reduce the size:

• Optimize images
• Remove unnecessary files
• Enable gzip compression
• Split large assets

"Too many requests"

You've hit the rate limit. Wait a minute and try again.

Development

Project Structure

cli/
├── src/
│   ├── commands/        # Command implementations
│   │   ├── login.ts
│   │   ├── deploy.ts
│   │   ├── list.ts
│   │   └── rollback.ts
│   ├── lib/            # Utilities
│   │   ├── api.ts      # API client
│   │   ├── config.ts   # Config management
│   │   ├── build.ts    # Build detection
│   │   └── zip.ts      # Zip creation
│   └── index.ts        # Entry point
├── package.json
└── tsconfig.json

Building

npm run build

Compiles TypeScript to dist/.

Local Testing

npm link
velar --help

Publishing

npm version patch
npm publish

Advanced Usage

CI/CD Integration

Store your token as a secret and use it in CI:

GitHub Actions:

- name: Deploy to Velar
  env:
    VELAR_TOKEN: ${{ secrets.VELAR_TOKEN }}
  run: |
    echo '{"token":"$VELAR_TOKEN","apiUrl":"https://velardev.app"}' > ~/.velar/config.json
    velar deploy --skip-build

GitLab CI:

deploy:
  script:
    - echo '{"token":"'$VELAR_TOKEN'","apiUrl":"https://velardev.app"}' > ~/.velar/config.json
    - velar deploy --skip-build

Custom Workflows

Deploy specific directory:

npm run build
velar deploy --dir dist --skip-build

Deploy with custom name:

velar deploy --name staging-v2

Troubleshooting

Check Configuration

cat ~/.velar/config.json

Verify Token

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://velardev.app/api/projects

Debug Mode

Add console logs in the CLI code and rebuild:

console.log('Debug:', config);

Clear Configuration

rm -rf ~/.velar
velar login

Security

• Never commit your .velar/config.json to version control
• Store tokens as environment variables in CI/CD
• Rotate tokens regularly
• Use different tokens for different environments

Changelog

v1.0.0

• Initial release
• Login, deploy, list, rollback commands
• Automatic build detection
• Progress indicators
• Error handling

Support

For issues or questions:

• GitHub Issues: github.com/velar/velar
• Documentation: velardev.app/docs

Built with ❤️ for developers