CLI

Offworld provides a CLI for creating reference files and managing git clones.

Prerequisites

Offworld uses opencode as its AI runtime for local reference generation. Install it before installing Offworld.

Verify the installation:

Installation

Install Script

The native install script is the recommended way to get started with Offworld.

Node.js

Using your node package manager of choice.

Homebrew

Using Homebrew on macOS or Linux.

Agent-native

Copy this prompt to let your coding agent install, configure, and initialize Offworld for you.

Install prompt

If you're an LLM agent helping set up Offworld CLI, ask the user for preferences first, then run non-interactive commands based on their answers.

Step 0: Ask for preferences (agent-guided)

Ask the user for:

Install method (install script vs package manager)
Agents to sync (e.g. opencode, claude, codex)
Clone directory (default ~/ow)
Model preference (provider/model) or use defaults
Dependency selection (all vs a curated list)

Use their answers to fill flags in the commands below. Avoid running interactive CLI flows.

Step 1: Check for opencode

opencode is required for local AI reference generation. Verify it's installed:

opencode --version

If not installed:

curl -fsSL https://opencode.ai/install | bash

Step 2: Install the CLI

curl -fsSL https://offworld.sh/install | bash

Or use your preferred package manager:

npm install -g offworld

Step 3: Initialize Offworld (non-interactive)

ow init --yes --agents "<agent-list>" --repo-root "<clone-dir>" --model "<provider/model>"

This will:

Create config at ~/.config/offworld/config.json
Set the clone directory (~/ow/)
Configure which agents to sync reference files to
Set the default model for reference generation

Step 4: Verify the installation

ow --version
ow config show

Step 5: Initialize in the current project (non-interactive)

ow project init --yes --all --generate

This will:

Scan package.json (or other manifest files) for dependencies
Install reference files for selected dependencies
Generate missing references when needed
Update AGENTS.md with a table of installed reference files

If you want a specific set of dependencies instead of --all:

ow project init --yes --deps "zod,typescript,vitest" --generate

Or exclude specific dependencies:

ow project init --yes --all --skip "react,react-dom" --generate

Step 6: Verify setup

List the installed reference files:

ow list

Troubleshooting

If reference files are not appearing, check:

Is the config valid? ow config show
Where is the config file? ow config path
Check the reference directory: ls ~/.local/share/offworld/skill/offworld/references/

Quick Start

After installing, get started in three steps.

1. Initialize in your project

2. Pull reference files for any repo

3. Use the reference file in your agent

Example prompt

Use the offworld skill. How do I set up file-based routing with tanstack/router?

The agent will read the reference, search the cloned source code, and answer questions fast.

Usage

The CLI accepts commands in the following format.

The primary workflow is project init, which scans your manifest files and generates reference files for your dependencies.

Commands

Core commands for managing reference files and repositories.

Command	Description
`init`	Initialize configuration with interactive setup
`project init`	Scan manifest, install reference files, update AGENTS.md
`pull`	Git pull a repository and fetch a reference from offworld.sh or generate one locally
`generate`	Generate reference file locally, if you want to always ignore the remote references
`push`	Push local reference file to offworld.sh, making it available for all users to pull
`list`	List managed repositories
`remove`	Remove a cloned repository and its reference file
`upgrade`	Upgrade offworld to latest or specific version
`uninstall`	Uninstall offworld and remove related files

init

Initialize configuration with interactive setup

Flags

--yes, -ySkip confirmation prompts

--force, -fReconfigure even if config exists

--model, -mAI provider/model

--repo-rootWhere to clone repos

--agents, -aComma-separated agents

The init command performs a complete one-time setup:

Prompts to authenticate with offworld.sh (optional, for push/pull shared references)
Configures where to clone repositories (default: ~/ow)
Selects your AI provider and model for local reference generation
Detects and selects which coding agents to symlink skill directory to
Installs the SKILL.md directory to ~/.local/share/offworld/skill/offworld/.

project init

Scan manifest, install reference files, update AGENTS.md

Flags

--allSelect all detected dependencies

--depsComma-separated deps to include

--skipComma-separated deps to exclude

--generate, -gGenerate reference files for deps without existing ones

--dry-run, -dShow what would be done

--yes, -ySkip confirmations

pull

Git pull a repository and fetch a reference from offworld.sh or generate one locally

Flags

--reference, -rReference file name (defaults to owner-repo)

--shallowUse shallow clone (--depth 1)

--sparseUse sparse checkout (only src/, lib/, packages/, docs/)

--branchBranch to clone

--force, -fForce re-generation

--model, -mModel override (provider/model)

generate

alias: gen

Generate reference file locally, if you want to always ignore the remote references

Flags

--force, -fForce even if remote exists

--model, -mModel override (provider/model)

push

Push local reference file to offworld.sh, making it available for all users to pull

list

alias: ls

List managed repositories

Flags

--jsonOutput as JSON

--pathsShow full paths

--staleOnly show stale repos

--patternFilter by pattern (e.g. 'react-*')

remove

alias: rm

Remove a cloned repository and its reference file

Flags

--yes, -ySkip confirmation

--reference-onlyOnly remove reference files (keep repo)

--repo-onlyOnly remove cloned repo (keep reference file)

--dry-run, -dShow what would be done

upgrade

Upgrade offworld to latest or specific version

uninstall

Uninstall offworld and remove related files

Flags

--keep-configKeep configuration files

--keep-dataKeep data files (references, repos)

--dry-run, -dShow what would be removed

--force, -fSkip confirmation

Subcommands

These commands have their own subcommands.

ow auth

Authenticate with offworld.sh to push and pull shared reference files

Command	Description
`login`	Login to offworld.sh
`logout`	Logout from offworld.sh
`status`	Show authentication status

ow config

Manage your Offworld configuration settings

Command	Description
`show`	Show all config settings
`set`	Set a config value
`get`	Get a config value
`reset`	Reset config to defaults
`path`	Show config file location
`agents`	Interactively select agents

ow map

Fast repo routing by name or keyword. Used by agents to resolve references

Command	Description
`show <repo>`	Show map entry for a repo (path, reference, keywords)
`search <term>`	Search map for repos matching a term or keyword

ow repo

Manage your local repository clones and map

Command	Description
`list`	List managed repositories
`update`	Update repos (git fetch + pull)
`prune`	Remove stale map entries
`status`	Show summary of managed repos
`gc`	Garbage collect old/unused repos
`discover`	Discover and map existing repos

Global Options

The Offworld CLI takes the following global flags.

Option	Short	Description
`--help`	-h	Show help message
`--version`	-V	Show version

Full documentation

CLI

Prerequisites

Installation

Install Script

Node.js

Homebrew

Agent-native

Step 0: Ask for preferences (agent-guided)

Step 1: Check for opencode

Step 2: Install the CLI

Step 3: Initialize Offworld (non-interactive)

Step 4: Verify the installation

Step 5: Initialize in the current project (non-interactive)

Step 6: Verify setup

Troubleshooting

Quick Start

Usage

Commands

init

project init

pull

generate

push

list

remove

upgrade

uninstall

Subcommands

ow auth

ow config

ow map

ow repo

Global Options

Navigate

Learn

Connect