tlon

Files (10)

• README.md
• SKILL.md
• tlon.js · bin/
• package.json
• auto-react.hoon · references/hooks-examples/
• delete-old-posts.hoon · references/hooks-examples/
• word-filter.hoon · references/hooks-examples/
• hooks.md · references/
• urbit-api.md · references/
• postinstall.js · scripts/

SKILL.md (first lines)

# Tlon Skill

Use the `tlon` command for all Tlon operations.

## Installation

**npm (Node.js):**
```bash
npm install @tloncorp/tlon-skill
tlon channels groups
```

**Direct binary (no Node required):**
```bash
curl -L https://registry.npmjs.org/@tloncorp/tlon-skill-darwin-arm64/-/tlon-skill-darwin-arm64-0.1.0.tgz | tar -xz
./package/tlon channels groups
```

Replace `darwin-arm64` with `darwin-x64` or `linux-x64` as needed.


## Configuration

**CLI Flags (highest priority):**
```bash
# Cookie-based auth (fastest - ship parsed from cookie name)
tlon --url https://your-ship.tlon.network --cookie "urbauth-~your-ship=0v..." <command>

# Code-based auth (requires url + ship + code)
tlon --url https://your-ship.tlon.network --ship ~your-ship --code sampel-ticlyt-migfun-falmel <command>

# Or load from a JSON config file
tlon --config ~/ships/my-ship.json <command>
```

Config file format:
```json
// Cookie-based (ship derived from cookie)
{"url": "...", "cookie": "urbauth-~ship=..."}

// Code-based
{"url": "...", "ship": "~...", "code": "..."}
```

**Environment Variables:**
```bash
# Cookie-based (ship derived from cookie)
export URBIT_URL="https://your-ship.tlon.network"
export URBIT_COOKIE="urbauth-~your-ship=0v..."

# Code-based
export URBIT_URL="https://your-ship.tlon.network"
export URBIT_SHIP="~your-ship"
export URBIT_CODE="sampel-ticlyt-migfun-falmel"
```

**OpenClaw:** If configured with a Tlon channel, credentials load automatically.

**Resolution order:** CLI flags → `TLON_CONFIG_FILE` → `URL + COOKIE` → `URL + SHIP + CODE` → `--ship` with cache → OpenClaw config → cached ships (auto-select if only one)

**Cookie vs Code:**
- **Cookie-based:** Uses pre-authenticated session cookie. Ship is parsed from the cookie name (`urbauth-~ship=...`). Fastest option.
- **Code-based:** Performs login to get session cookie. Requires URL + ship + code.

You can provide both cookie and code — cookie is used first, code serves as fallback if cookie expires.

## Cookie Caching

The skill automatically caches auth cookies to `~/.tlon/cache/<ship>.json` after successful authentication. This makes subsequent invocations much faster by skipping the login request.

**How it works:**
```bash
# First time - authenticates and caches
$ tlon --url https://zod.tlon.network --ship ~zod --code abcd-efgh contacts self
~zod
Note: Credentials cached for ~zod. Next time just run: tlon <command>

# After that - no flags needed (if only one cached ship)
$ tlon contacts self
~zod

# With multiple cached ships - specify which one
$ tlon --ship ~zod contacts self
$ tlon --ship ~bus contacts self
```

**Cache behavior:**
- Cached cookies are URL-specific (won't use a cookie for the wrong host)
- If only one ship is cached, it's auto-selected (no flags needed)
- If multiple ships are cached, you'll be prompted to specify with `--ship`
- The skill reminds you when you pass credentials that aren't needed

**Clear cache:** `rm ~/.tlon/cache/*.json`



## Multi-Ship Usage

If you have credentials for multiple ships, you can use this skill to operate on behalf of any of them. This is useful for:

- **Managing multiple identities** — switch between ships without changing environment variables
- **Bot operations** — act as a bot ship while authenticated as yourself
- **Moon management** — operate moons from their parent planet

Simply pass the target ship's credentials via CLI flags:

```bash
# Post to a channel as ~other-ship
tlon --url https://other-ship.tlon.network --ship ~other-ship --code their-access-code \
  posts send chat/~host/channel "Hello from other-ship"

# Or keep credentials in config files
tlon --config ~/ships/bot.json channels groups
tlon --config ~/ships/moon.json contacts self
```

## Commands

### Activity

From BlackXV2vip/wormagent, MIT.

More from BlackXV2vip/wormagent