Installation

This guide covers all methods for installing and configuring Better Skills, including CLI installation, web dashboard access, and environment setup for local development.

CLI Installation

The Better Skills CLI is distributed as a pre-compiled binary for macOS and Linux.

Supported Platforms

Operating System	Architectures
macOS (Darwin)	x64, arm64 (Apple Silicon)
Linux	x64, arm64

Windows support is not yet available. Consider using WSL2 (Windows Subsystem for Linux) as a workaround.

Quick Install (Recommended)

The fastest way to install the CLI is with the one-line installer:

curl -fsSL https://better-skills.dev/install | bash

This script:

Detects your OS and architecture
Downloads the latest release from GitHub
Installs to ~/.local/bin/better-skills
Creates a wrapper script with the default server URL

The installer is idempotent—running it again will upgrade to the latest version.

Custom Installation Options

You can customize the installation with options:

curl -fsSL https://better-skills.dev/install | bash -s -- --version v0.1.0

Installer Options

Option	Description	Default
`--version <tag>`	Specific release tag to install	`latest`
`--install-dir <path>`	Installation directory	`$HOME/.local/bin`
`--server-url <url>`	Default API server URL	`https://server.better-skills.dev`
`--repo <owner/repo>`	GitHub repository for releases	`LeonardoTrapani/better-skills`
`-h, --help`	Show installer help	-

Manual Installation

For advanced users or custom setups, you can install manually:

Download the Binary

Go to the GitHub Releases page and download the appropriate binary for your platform:

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

Make Executable

Add execute permissions:

chmod +x better-skills-darwin-arm64

Move to PATH

Move the binary to a directory in your PATH:

mv better-skills-darwin-arm64 ~/.local/bin/.better-skills-bin

Create Wrapper Script

Create a wrapper script to set environment variables:

wrapper.sh

#!/usr/bin/env bash
set -euo pipefail
SERVER_URL="${SERVER_URL:-https://server.better-skills.dev}" \
  BETTER_SKILLS_VERSION="v0.1.0" \
  exec "$HOME/.local/bin/.better-skills-bin" "$@"

Make it executable and move to PATH:

chmod +x wrapper.sh
mv wrapper.sh ~/.local/bin/better-skills

Verify Installation

After installation, verify the CLI is working:

better-skills --version
# Output: better-skills v0.1.0

If you see command not found, ensure ~/.local/bin is in your PATH. See PATH Configuration below.

PATH Configuration

If the CLI is not found after installation, add the installation directory to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify with:

echo $PATH | grep -o "$HOME/.local/bin"

Web Dashboard

The Better Skills web dashboard is hosted at: https://better-skills.dev No installation is required—simply visit the URL and sign in with your account.

Features

Skill Browser: Browse and search skills across all your vaults
Skill Editor: Create and edit skills with markdown preview
Graph Visualizer: Explore skill-to-skill and skill-to-resource relationships
Vault Management: Create vaults, invite members, configure permissions
Settings: Manage account preferences, vault memberships, and API keys

Access Requirements

A Better Skills account (sign up at better-skills.dev)
Modern browser (Chrome, Firefox, Safari, Edge)
Internet connection

The web dashboard shares the same authentication as the CLI. Logging in to one automatically authenticates the other.

Environment Setup

Configure the CLI with environment variables or a config file.

Environment Variables

The CLI reads configuration from environment variables:

Variable	Description	Default
`SERVER_URL`	API server base URL	`http://localhost:3000` (dev) `https://server.better-skills.dev` (prod)
`AGENTS`	Comma-separated list of target agents for sync	`opencode`
`BETTER_SKILLS_INSTALL_DIR`	Installation directory for installer script	`$HOME/.local/bin`
`BETTER_SKILLS_SERVER_URL`	Server URL baked into installer wrapper	`https://server.better-skills.dev`
`BETTER_SKILLS_REPO`	GitHub repo for releases	`LeonardoTrapani/better-skills`

export SERVER_URL="https://my-server.example.com"
better-skills health

Config File

Alternatively, create a .better-skills.json config file in your project directory:

.better-skills.json

{
  "serverUrl": "https://server.better-skills.dev",
  "agents": ["opencode", "cursor"],
  "vaults": {
    "personal": {
      "enabled": true
    },
    "my-enterprise-vault": {
      "enabled": false
    }
  }
}

The CLI will read this file from the current working directory.

Environment variables take precedence over the config file.

Session Storage

After running better-skills login, your session is stored at:

~/.better-skills/session.json

This file contains:

accessToken: OAuth2 access token
tokenType: Token type (usually Bearer)
expiresIn: Token expiration time in seconds

Do not commit session.json to version control. It contains sensitive credentials.

To logout and remove the session:

better-skills logout

Local Development Setup

To run Better Skills from source (for contributors):

Clone the Repository

git clone https://github.com/LeonardoTrapani/better-skills.git
cd better-skills

Install Dependencies

Better Skills uses Bun as the package manager:

bun install

Do not use npm, yarn, or pnpm. The project is configured for Bun workspaces.

Setup Database

The project uses PostgreSQL with Drizzle ORM. Start a local Postgres instance:

brew services start postgresql@17

Then apply the schema:

bun run db:push

Configure Environment

Copy the example environment files:

cp apps/server/.env.example apps/server/.env
cp apps/web/.env.example apps/web/.env

Edit apps/server/.env:

apps/server/.env

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/better_skills"
BETTER_AUTH_SECRET="<generate-random-secret>"
BETTER_AUTH_URL="http://localhost:3000"
CORS_ORIGIN="http://localhost:3001"

Edit apps/web/.env:

apps/web/.env

NEXT_PUBLIC_SERVER_URL="http://localhost:3000"

Start Development Servers

Run all services in development mode:

bun run dev

This starts:

Web: http://localhost:3001
API: http://localhost:3000

Or start individually:

bun run dev:web

Required Environment Variables (Development)

Server (apps/server/.env):

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@localhost:5432/db`
`BETTER_AUTH_SECRET`	Secret key for Better Auth	`<random-64-char-string>`
`BETTER_AUTH_URL`	Auth callback base URL	`http://localhost:3000`
`CORS_ORIGIN`	Allowed CORS origin	`http://localhost:3001`

Web (apps/web/.env):

Variable	Description	Example
`NEXT_PUBLIC_SERVER_URL`	API server base URL	`http://localhost:3000`

CLI (set in shell):

Variable	Description	Example
`SERVER_URL`	API server base URL	`http://localhost:3000`

Validation Commands

After making changes, run validation:

bun run check-types

Updating

Update CLI

Re-run the installer to upgrade to the latest version:

curl -fsSL https://better-skills.dev/install | bash

Or install a specific version:

curl -fsSL https://better-skills.dev/install | bash -s -- --version v0.2.0

Update Dependencies (Development)

Update all workspace dependencies:

bun update

Uninstalling

To remove the Better Skills CLI:

Remove Binary

rm ~/.local/bin/better-skills
rm ~/.local/bin/.better-skills-bin

Remove Session

rm -rf ~/.better-skills

Remove Synced Skills (Optional)

rm -rf .agents/skills

Next Steps

Quickstart

Follow the quickstart to login and sync your first skill

CLI Commands

Explore all available CLI commands

Web Dashboard

Learn how to use the web interface

Authentication

Learn about authentication and session management

Get Started

Core Concepts

Web Dashboard

CLI Tool

Guides

Installation

Installation

CLI Installation

Supported Platforms

Quick Install (Recommended)

Custom Installation Options

Installer Options

Manual Installation

Verify Installation

PATH Configuration

Web Dashboard

Features

Access Requirements

Environment Setup

Environment Variables

Config File

Session Storage

Local Development Setup

Required Environment Variables (Development)

Validation Commands

Updating

Update CLI

Update Dependencies (Development)

Uninstalling

Next Steps

Quickstart

CLI Commands

Web Dashboard

Authentication

Build docs developers (and LLMs) love

Get Started

Core Concepts

Web Dashboard

CLI Tool

Guides

​Installation

​CLI Installation

​Supported Platforms

​Quick Install (Recommended)

​Custom Installation Options

​Installer Options

​Manual Installation

​Verify Installation

​PATH Configuration

​Web Dashboard

​Features

​Access Requirements

​Environment Setup

​Environment Variables

​Config File

​Session Storage

​Local Development Setup

​Required Environment Variables (Development)

​Validation Commands

​Updating

​Update CLI

​Update Dependencies (Development)

​Uninstalling

​Next Steps

Quickstart

CLI Commands

Web Dashboard

Authentication

Build docs developers (and LLMs) love

Installation

CLI Installation

Supported Platforms

Quick Install (Recommended)

Custom Installation Options

Installer Options

Manual Installation

Verify Installation

PATH Configuration

Web Dashboard

Features

Access Requirements

Environment Setup

Environment Variables

Config File

Session Storage

Local Development Setup

Required Environment Variables (Development)

Validation Commands

Updating

Update CLI

Update Dependencies (Development)

Uninstalling

Next Steps