---
title: hub
description: Named workspace connections for pushing, pulling, and sharing artifacts on Hub.
---

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

A hub connection is a named link between your local Treeship and a workspace on Hub. You push receipts to it. Other people verify them there. Think of hub connections like tmux sessions -- named connections you can attach, detach, and kill independently.

Most developers need exactly one hub connection. Multiple hub connections exist when receipts need to go to separate workspaces (personal vs work, your company vs a client).

## Commands

| Command | Description |
|---------|-------------|
| `treeship hub attach` | Connect to Hub (creates new or reconnects) |
| `treeship hub detach` | Disconnect active hub connection (keeps keys) |
| `treeship hub ls` | List all known hub connections |
| `treeship hub status` | Show active hub connection details |
| `treeship hub use <name>` | Switch active hub connection |
| `treeship hub push <id>` | Push artifact to active hub connection |
| `treeship hub pull <id>` | Pull artifact from Hub |
| `treeship hub open` | Open workspace in browser |
| `treeship hub kill <name>` | Remove a hub connection |

## treeship hub attach

Connects to Hub. If the hub connection name already exists locally with keys, reconnects without re-authenticating. If new, runs the device flow.

<Tabs items={['Basic', 'Named', 'Reconnect']}>
<Tab value="Basic">
```bash
treeship hub attach
```

```
  visit treeship.dev/hub/activate
  code: 4b0a-6d36

attached
  name:      default
  hub id:    hub_661e5463912d
  endpoint:  api.treeship.dev

next steps:
  treeship status                                check ship + hub state
  treeship attest receipt --system system://<your-system> \
    --kind <kind> --payload-file <file>          sign an external receipt
  treeship hub push <artifact-id>                share a signed artifact
  treeship verify <artifact-id>                  verify it anywhere

  example (memory proof):
    treeship attest receipt --system system://zmem --kind memory.proof \
      --payload-file proof.json

  view your workspace: treeship hub open
```

The `next steps` commands are provider-neutral templates. The example shows one customer's memory-proof workflow (`system://zmem`, `memory.proof`); `--system` and `--kind` accept any value.
</Tab>
<Tab value="Named">
```bash
treeship hub attach --name acme-corp
```

Creates a hub connection named "acme-corp" pointing at a separate workspace.
</Tab>
<Tab value="Reconnect">
```bash
treeship hub attach --name acme-corp
```

If "acme-corp" already exists with keys, reconnects instantly without the browser flow.

```
reconnected
  hub:      acme-corp
  hub id:   hub_f7e6d5c4b3a2
```
</Tab>
</Tabs>

| Option | Description |
|--------|-------------|
| `--name <name>` | Hub connection name (default: "default") |
| `--endpoint <url>` | Hub API endpoint (default: `https://api.treeship.dev`) |

<Callout type="warn" title="DPoP Security">
All Hub requests use RFC 9449 DPoP proof-of-possession. Every request carries a DPoP JWT signed by the hub key. Stolen credentials are useless without the private key.
</Callout>

## treeship hub detach

Disconnects the active hub connection. Keys are preserved locally so you can reconnect later.

```bash
treeship hub detach
```

```
detached from acme-corp
  keys preserved
  reconnect: treeship hub use acme-corp
```

## treeship hub ls

Lists all known hub connections.

```bash
treeship hub ls
```

```
NAME             HUB ID                   ENDPOINT                         STATUS
--------------------------------------------------------------------------------
default          hub_661e5463912d         api.treeship.dev                 active
work             hub_a2b3c4d5e6f7         api.treeship.dev
acme-corp        hub_f7e6d5c4b3a2         api.treeship.dev
```

## treeship hub status

Shows the currently active hub connection with details.

```bash
treeship hub status
```

```
hub:       default
hub id:    hub_661e5463912d
key:       key_9f8e7d6c (ed25519)
endpoint:  api.treeship.dev
workspace: treeship.dev/workspace/hub_661e5463912d
```

## treeship hub use

Switches the active hub connection without re-authenticating. Accepts name or hub ID.

```bash
treeship hub use work
treeship hub use hub_a2b3c4d5e6f7
```

## treeship hub push

Push an artifact to Hub. Returns a shareable verify URL.

<Tabs items={['Active hub', 'Specific hub', 'All hubs']}>
<Tab value="Active hub">
```bash
treeship hub push art_f7e6d5c4
treeship hub push last
```
</Tab>
<Tab value="Specific hub">
```bash
treeship hub push art_f7e6d5c4 --hub acme-corp
treeship hub push last --hub work
```
</Tab>
<Tab value="All hubs">
```bash
treeship hub push art_f7e6d5c4 --all
```

Pushes to every known hub connection. The verify URL is the same across all hub connections -- artifacts are content-addressed.
</Tab>
</Tabs>

| Option | Description |
|--------|-------------|
| `--hub <name\|id>` | Push to a specific hub connection |
| `--all` | Push to all known hub connections |

## treeship hub pull

Pull an artifact from Hub into local storage. No authentication required.

```bash
treeship hub pull art_f7e6d5c4
treeship hub pull art_f7e6d5c4 --hub acme-corp
```

## treeship hub open

Opens the active workspace in the browser. Prints the URL regardless.

```bash
treeship hub open
treeship hub open --hub acme-corp
treeship hub open --no-open
```

## treeship hub kill

Removes a hub connection from local config. Prompts for confirmation.

```bash
treeship hub kill acme-corp
treeship hub kill acme-corp --force
```

Artifacts already pushed to Hub remain there -- they are content-addressed and independently verifiable. Only the ability to push new artifacts to that workspace is removed.

## Config

Hub connections are stored in `~/.treeship/config.json`:

```json
{
  "hub_connections": {
    "default": {
      "hub_id": "hub_661e5463912d",
      "key_id": "key_9f8e7d6c",
      "endpoint": "api.treeship.dev"
    },
    "work": {
      "hub_id": "hub_a2b3c4d5e6f7",
      "key_id": "key_9f8e7d6c",
      "endpoint": "api.treeship.dev"
    }
  },
  "active_hub": "default"
}
```

<Callout type="info">
Configs from v0.1/v0.2 (flat `hub` object) are automatically migrated to the new `hub_connections` format on first run. No manual action required.
</Callout>
