Skip to main content
Gambiarra consists of two main packages:
  • CLI (gambiarra) - Command-line tool for managing hubs and participants
  • SDK (gambiarra-sdk) - TypeScript library for integrating with the Vercel AI SDK

​
CLI installation

The CLI allows you to start hubs, create rooms, and join as a participant.
The standalone binary installation via curl is recommended as it requires no additional dependencies.

​
Verify installation

Check that the CLI is installed correctly: 
gambiarra --version
You should see the version number printed to the console.

​
Getting help

View available commands: 
gambiarra --help
View help for a specific command: 
gambiarra serve --help
gambiarra create --help
gambiarra join --help
gambiarra list --help

​
SDK installation

The SDK provides Vercel AI SDK integration for using shared LLMs in your applications. 
npm install gambiarra-sdk ai
The ai package (Vercel AI SDK) is a peer dependency required for the SDK to work.

​
Basic usage

Once installed, you can use the SDK in your TypeScript/JavaScript applications: 
import { createGambiarra } from "gambiarra-sdk";
import { generateText } from "ai";

const gambiarra = createGambiarra({
  roomCode: "ABC123",
  hubUrl: "http://localhost:3000", // optional, defaults to localhost:3000
});

const result = await generateText({
  model: gambiarra.any(),
  prompt: "Hello, Gambiarra!",
});

console.log(result.text);

​
Uninstall

​
Uninstall CLI

Remove the CLI based on how you installed it:
Remove the standalone binary:
sudo rm /usr/local/bin/gambiarra

​
Uninstall SDK

Remove the SDK from your project: 
npm uninstall gambiarra-sdk

​
Requirements

​
CLI requirements

  • No dependencies when using the standalone binary (curl installation)
  • Node.js 18+ or Bun 1.0+ when using npm/bun installation
  • Linux, macOS, or Windows (via WSL)

​
SDK requirements

  • Node.js 18+ or Bun 1.0+
  • Vercel AI SDK (ai package) version 3.0 or higher

​
Platform-specific notes

​
macOS

The CLI works out of the box on macOS. If you install via curl, you may need to grant execute permissions: 
chmod +x /usr/local/bin/gambiarra
For mDNS support, no additional setup is required as Bonjour is built into macOS.

​
Linux

For mDNS support on Linux, you need Avahi: 
# Ubuntu/Debian
sudo apt-get install avahi-daemon avahi-utils

# Fedora/RHEL
sudo dnf install avahi avahi-tools

# Arch Linux
sudo pacman -S avahi
Start the Avahi daemon: 
sudo systemctl start avahi-daemon
sudo systemctl enable avahi-daemon

​
Windows

Windows support is available through WSL (Windows Subsystem for Linux):
  1. Install WSL 2: https://docs.microsoft.com/en-us/windows/wsl/install
  2. Install Ubuntu or your preferred Linux distribution
  3. Follow the Linux installation instructions above
Native Windows support is not currently available. Please use WSL.

​
Updating

​
Update CLI

Re-run the installation script:
curl -fsSL https://raw.githubusercontent.com/arthurbm/gambiarra/main/scripts/install.sh | bash

​
Update SDK

Update the SDK in your project: 
npm update gambiarra-sdk

​
Troubleshooting

​
CLI not found after installation

If the gambiarra command is not found after installation:
  1. Check your PATH - Ensure /usr/local/bin is in your PATH: 
    echo $PATH | grep /usr/local/bin
  2. Reload your shell - Close and reopen your terminal, or run: 
    source ~/.bashrc  # or ~/.zshrc for zsh
  3. Verify the binary exists: 
    ls -la /usr/local/bin/gambiarra

​
Permission denied

If you get a permission denied error when installing via curl: 
# The install script needs sudo access to write to /usr/local/bin
# Make sure you're running the script with appropriate permissions
curl -fsSL https://raw.githubusercontent.com/arthurbm/gambiarra/main/scripts/install.sh | sudo bash

​
SDK import errors

If you get import errors with the SDK:
  1. Check that ai is installed - The Vercel AI SDK is a peer dependency: 
    npm list ai
  2. Ensure TypeScript is configured - Add to your tsconfig.json: 
    {
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2022"
  }
}
  3. Check Node.js version - Ensure you’re running Node.js 18 or higher: 
    node --version

​
mDNS not working

If mDNS discovery isn’t working:
  • On Linux: Install and start Avahi (see Linux section above)
  • On macOS: mDNS should work out of the box
  • Firewall: Ensure UDP port 5353 is not blocked
  • Network: Both hub and clients must be on the same local network

​
Next steps

Quickstart

Get up and running with Gambiarra

CLI reference

Learn about all CLI commands

SDK reference

Use Gambiarra in your apps

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us