Skip to content

INSTALLATION-SETUP.md

Latest commit

 

History

History
213 lines (147 loc) · 4.84 KB

INSTALLATION-SETUP.md

File metadata and controls

213 lines (147 loc) · 4.84 KB

Conduct CLI Installation Setup

This document explains the installation approach for Conduct CLI, similar to Claude's installation script.

Overview

Conduct CLI supports three installation methods:

  1. Standalone Binaries (Recommended) - Pre-compiled executables via install.sh
  2. Bun - Fast JavaScript runtime
  3. npm - Traditional Node.js package manager

Installation Flow

Method 1: Shell Script (Recommended)

curl -fsSL https://git.conduct.run/install.sh | bash

How it works:

  1. Detects platform (darwin/linux) and architecture (x64/arm64)
  2. Fetches latest version from GitHub releases
  3. Downloads pre-compiled binary for the platform
  4. Verifies SHA256 checksum (if available)
  5. Installs to $HOME/.local/bin/conduct
  6. Fallback: If binary not found, uses Bun or npm

Method 2: Bun

bun install -g conduct-cli

Method 3: npm

npm install -g conduct-cli

Building Standalone Executables

Local Build

cd cli
npm run build:standalone

This generates:

  • binaries/conduct-darwin-x64
  • binaries/conduct-darwin-arm64
  • binaries/conduct-linux-x64
  • binaries/conduct-linux-arm64
  • binaries/checksums.txt

Automated Release (GitHub Actions)

When you push a git tag like v0.1.1, the GitHub Actions workflow automatically:

  1. Builds standalone binaries for all platforms using Bun
  2. Generates SHA256 checksums
  3. Creates GitHub release with all binaries attached
  4. Publishes to npm registry

Workflow file: .github/workflows/release.yml

Release Process

1. Update Version

cd cli
npm version patch  # or minor, major

This updates package.json to v0.1.2 (for example).

2. Commit and Tag

git add .
git commit -m "Release v0.1.2"
git tag v0.1.2
git push origin main --tags

3. Automatic Build

GitHub Actions workflow triggers on the v*.*.* tag and:

  • Builds binaries
  • Creates release
  • Publishes to npm (requires NPM_TOKEN secret)

4. Users Install

curl -fsSL https://git.conduct.run/install.sh | bash

Security Features

Checksum Verification

The install script verifies SHA256 checksums:

# Generated during build
shasum -a 256 conduct-* > checksums.txt

# Verified during install
actual=$(shasum -a 256 conduct-darwin-arm64 | cut -d' ' -f1)
expected=$(grep conduct-darwin-arm64 checksums.txt | cut -d' ' -f1)

if [ "$actual" != "$expected" ]; then
    echo "❌ Checksum verification failed"
    exit 1
fi

Binary Hosting

Binaries are hosted on GitHub Releases at:

https://github.com/21nOrg/conduct/releases/download/v0.1.1/conduct-darwin-arm64

Fallback Strategy

The install script has a robust fallback chain:

  1. Try GitHub binary → If not found...
  2. Try Bun install → If Bun not available...
  3. Try npm install → If npm not available...
  4. Error message with installation instructions

This ensures users can always install, even if:

  • New platform support is needed
  • GitHub releases are unavailable
  • Pre-compiled binaries fail

Supported Platforms

Currently supported platforms for standalone binaries:

  • darwin-x64 (macOS Intel)
  • darwin-arm64 (macOS Apple Silicon)
  • linux-x64 (Linux x86_64)
  • linux-arm64 (Linux ARM64)

Note: Windows users should use npm install -g conduct-cli

Installation Options

Users can specify version:

# Latest stable (default)
curl -fsSL https://git.conduct.run/install.sh | bash

# Specific version
curl -fsSL https://git.conduct.run/install.sh | bash -s 0.1.1

# Latest (same as stable)
curl -fsSL https://git.conduct.run/install.sh | bash -s latest

File Structure

cli/
├── build-standalone.sh      # Builds Bun executables
├── binaries/                # Git-ignored build output
│   ├── conduct-darwin-x64
│   ├── conduct-darwin-arm64
│   ├── conduct-linux-x64
│   ├── conduct-linux-arm64
│   └── checksums.txt
├── package.json             # build:standalone script
└── ...

.github/workflows/
└── release.yml              # Automated release workflow

install.sh                   # Installation script (repo root)

GitHub Secrets Required

For automated releases, configure these secrets in GitHub:

  1. NPM_TOKEN - npm publish token

License

The CLI is licensed under MIT (as of v0.1.1).

Benefits of This Approach

  1. ✅ Fast Installation - Single binary, no Node.js required
  2. ✅ Small Size - Bun compiles to optimized executables
  3. ✅ Security - SHA256 checksum verification
  4. ✅ Reliable - Fallback to npm/Bun if binaries fail
  5. ✅ Automated - GitHub Actions handles everything
  6. ✅ Cross-platform - macOS and Linux support

Made with ❤️ by 21nOrg