## Getting Started

POSH is a documentation viewer for Ruby developers. It works on macOS and Linux.

### Installation
Install with Homebrew:

```bash
brew install --cask skatkov/tap/poshtui
```

On Arch Linux, install the prebuilt package from the AUR:

```bash
yay -S poshtui-bin
```

Or download the executable manually from [GitHub Releases](https://github.com/skatkov/homebrew-tap/releases).

### Usage

Go into any Ruby project with a `Gemfile.lock` and run `posh sync`. This will download all documentation to your machine.

After that, just run `posh` inside a project and it will present a TUI interface.

It's also possible to clear all docsets from your machine by running `posh clear`.

### Selecting a Gemfile.lock

Posh needs a lockfile because it contains the exact Ruby and gem versions used by your project. By default, it finds the nearest `Gemfile`, searching from the current directory toward its parents, and uses its `Gemfile.lock`.

This means you can run Posh from a subdirectory of a Ruby project without passing the lockfile path manually.

Use `--lockfile` to bypass automatic detection and open a specific lockfile:

```bash
posh --lockfile=gemfiles/rails_8.gemfile.lock
posh sync --lockfile=gemfiles/rails_8.gemfile.lock
```

#### Missing lockfiles

If your project has a `Gemfile` but no `Gemfile.lock`, run `bundle install` in the project directory first. Posh cannot use `Gemfile` as a fallback because it contains version constraints rather than exact resolved versions.

In a monorepo, run Posh from the Ruby application directory. Posh searches parent directories but does not recursively scan unrelated applications.

## Use POSH with your coding harness

The documentation browser is free, with no limits. Basic commands like `posh sync` are free too.

You need a license for the AI tools below.

### Activate and sync

Get your license key from the customer portal linked in your Polar email.
Replace `YOUR_LICENSE_KEY` below. Keep the key out of agent chats and MCP configuration.

```bash
posh activate YOUR_LICENSE_KEY
posh status
```

From a Ruby project with a `Gemfile.lock`, run:

```bash
posh sync
```

This downloads available project docs. Run it again after changing dependencies.

### CLI

Open your harness in the same project. The agent needs shell access and `posh`
on its `PATH`.

Give it this instruction:

> Use POSH for this project's Ruby and gem docs. Run `posh --help` first.

Save it in your harness's project instructions.

- `posh docsets`: list installed documentation.
- `posh search QUERY`: find APIs.
- `posh read DOCUMENT_REF`: read a search result.

Replace `QUERY` with a search term and `DOCUMENT_REF` with a reference returned by search.

### MCP

Add a local server to your harness's MCP configuration:

- **Command:** `posh`
- **Arguments:** `["mcp", "--project", "/absolute/path/to/project"]`
- **Transport:** `stdio`

Use your project's absolute path. If `posh` is not on the harness's `PATH`, use
the executable path returned by `command -v posh`.

The harness launches the server. Run `posh sync` before connecting; MCP tools
are read-only. Update `--project` when switching projects.

## Contact
For questions or issues with POSH, email [contact@poshtui.com](mailto:contact@poshtui.com). For company enquiries and other matters, see the [contact page](/contact).