# How to Parse a Tailcat Token and View Its Contents as JSON

> Learn how to parse a Tailcat token and decode its CBOR data into human-readable JSON. Use ParseConnBlobRaw or ParseConnBlob for detailed insights.

- Repository: [Tailscale/tailcat](https://github.com/tailscale/tailcat)
- Tags: how-to-guide
- Published: 2026-08-30

---

**Tailcat tokens (also called ConnBlobs) are CBOR-encoded connection strings that you can decode to JSON using either the `ParseConnBlobRaw` function for raw CBOR data or `ParseConnBlob` for fully restored fields, with the CLI providing a built-in `parse` command for quick inspection.**

Tailcat encodes connection information into tokens using CBOR serialization wrapped in base64url encoding. These tokens, identifiable by their `tc` prefix, contain critical mesh network data including server public keys and DERP region mappings. Whether you need to debug connectivity issues or inspect node configurations programmatically, the tailscale/tailcat repository provides both library functions and command-line tools to parse a Tailcat token and render it as readable JSON.

## Understanding Tailcat Token Structure

Before parsing, it helps to understand what these tokens contain. A **ConnBlob** (the internal name for a Tailcat token) stores server public key material, DERP region information, node identifiers, and region routing data. The physical representation is a `tc`-prefixed, base-64 URL-safe string that encapsulates CBOR-encoded binary data. According to the source code in [`tailcat.go`](https://github.com/tailscale/tailcat/blob/main/tailcat.go), this format minimizes token size while preserving cryptographic and network topology details.

## Core Parsing Functions

The tailscale/tailcat library exposes two primary functions for token decoding in [`tailcat.go`](https://github.com/tailscale/tailcat/blob/main/tailcat.go), differentiated by their field restoration behavior.

### ParseConnBlobRaw for Raw CBOR Decoding

Located at lines 28-30 of [`tailcat.go`](https://github.com/tailscale/tailcat/blob/main/tailcat.go), **`ParseConnBlobRaw`** decodes the token's CBOR payload without synthesizing additional fields. This function returns exactly what is encoded in the wire format, making it ideal for inspecting the raw stored data or when you want to avoid side effects from field reconstruction. The CLI's `parse` sub-command leverages this function specifically for its JSON output.

### ParseConnBlob for Full Field Restoration

At lines 32-35 of [`tailcat.go`](https://github.com/tailscale/tailcat/blob/main/tailcat.go), **`ParseConnBlob`** performs a complete decode that restores omitted fields such as **RegionID** and node names. This method reconstructs the full connection information structure that the encoder may have optimized away, providing a complete view of the network topology and node metadata.

## Programmatic Token Parsing in Go

For applications integrating Tailcat connectivity, you can parse tokens directly using the Go API.

### Decoding Raw CBOR Data

To extract the raw CBOR contents as JSON without field synthesis:

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/tailscale/tailcat"
)

func main() {
	if len(os.Args) != 2 {
		log.Fatalf("usage: %s <token>", os.Args[0])
	}
	token := tailcat.ConnBlob(os.Args[1])

	// Decode the raw CBOR (the version the CLI “parse” command uses)
	val, err := tailcat.ParseConnBlobRaw(token)
	if err != nil {
		log.Fatalf("decode error: %v", err)
	}
	enc := json.NewEncoder(os.Stdout)
	enc.SetIndent("", "    ")
	if err := enc.Encode(val); err != nil {
		log.Fatalf("json encode error: %v", err)
	}
}

```

This approach uses `tailcat.ParseConnBlobRaw(token)` and outputs the structure using Go's standard `encoding/json` package with indentation.

### Full Decoding with Derived Fields

To restore the complete connection information including region mappings and node identifiers:

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/tailscale/tailcat"
)

func main() {
	if len(os.Args) != 2 {
		log.Fatalf("usage: %s <token>", os.Args[0])
	}
	token := tailcat.ConnBlob(os.Args[1])

	ci, err := tailcat.ParseConnBlob(token) // restores region & node names
	if err != nil {
		log.Fatalf("parse error: %v", err)
	}
	b, _ := json.MarshalIndent(ci, "", "    ")
	fmt.Println(string(b))
}

```

Here, `tailcat.ParseConnBlob(token)` handles the reconstruction of region IDs and node names that were elided during encoding, returning a fully populated struct suitable for marshaling to JSON.

## Command-Line Token Inspection

For quick debugging without writing code, the Tailcat CLI includes a dedicated `parse` sub-command. Implemented in [`cmd/tailcat/tailcat.go`](https://github.com/tailscale/tailcat/blob/main/cmd/tailcat/tailcat.go) at lines 56-68, this command internally calls `ParseConnBlobRaw` and formats the output as indented JSON.

```bash

# Suppose you have a token like "tc...."

$ tailcat parse <token>
{
    "ServerPublic": {
        "Key": "AQID... (base64‑encoded public key)",
        "LegacyKey": ""
    },
    "Region": [
        {
            "RegionID": 1,
            "RegionCode": "1",
            "Nodes": [
                {
                    "Name": "node-abc",
                    "HostName": "node-abc",
                    "RegionID": 1,
                    "Key": "AQID..."
                }
            ]
        }
    ],
    "RegionID": 1
}

```

The command accepts the token string directly and prints the decoded CBOR structure, including ServerPublic keys and Region arrays, to standard output.

## Implementation Reference

Understanding the source layout helps when integrating these parsing capabilities:

- **[`tailcat.go`](https://github.com/tailscale/tailcat/blob/main/tailcat.go)** (lines 28-35): Core definitions of `ConnBlob`, `ParseConnBlobRaw`, and `ParseConnBlob`. Implements CBOR decode logic and region-field restoration.
- **[`cmd/tailcat/tailcat.go`](https://github.com/tailscale/tailcat/blob/main/cmd/tailcat/tailcat.go)** (lines 56-68): CLI entry point providing the `parse` sub-command that consumes `ParseConnBlobRaw` for JSON output.
- **[`wire.go`](https://github.com/tailscale/tailcat/blob/main/wire.go)**: Defines the internal `wireConnInfo` struct used during CBOR unmarshalling, representing the wire format of the connection information.

## Summary

- **Tailcat tokens** (ConnBlobs) use CBOR encoding within base64url strings prefixed with `tc`.
- **`ParseConnBlobRaw`** in [`tailcat.go`](https://github.com/tailscale/tailcat/blob/main/tailcat.go) returns raw CBOR-decoded data without synthesized fields, used by the CLI `parse` command.
- **`ParseConnBlob`** restores omitted fields like RegionID and node names for complete connection information.
- The **CLI tool** provides immediate JSON inspection via `tailcat parse <token>`, implemented in [`cmd/tailcat/tailcat.go`](https://github.com/tailscale/tailcat/blob/main/cmd/tailcat/tailcat.go).
- Both methods are available in the `github.com/tailscale/tailcat` package for integration into Go applications.

## Frequently Asked Questions

### What format does a Tailcat token use?

Tailcat tokens (ConnBlobs) are base64url-encoded strings prefixed with `tc` that contain CBOR-serialized connection information. This format stores server public keys, DERP region data, and node identifiers in a compact binary representation defined in [`wire.go`](https://github.com/tailscale/tailcat/blob/main/wire.go) and decoded via the functions in [`tailcat.go`](https://github.com/tailscale/tailcat/blob/main/tailcat.go).

### What's the difference between ParseConnBlobRaw and ParseConnBlob?

**`ParseConnBlobRaw`** (lines 28-30 of [`tailcat.go`](https://github.com/tailscale/tailcat/blob/main/tailcat.go)) decodes only the raw CBOR fields stored in the token without adding computed fields. **`ParseConnBlob`** (lines 32-35) performs the same decoding but restores omitted data such as region IDs and node names, providing a complete connection information structure suitable for full network topology reconstruction.

### How do I parse a Tailcat token from the command line?

Use the `tailcat parse <token>` command. This CLI tool, implemented in [`cmd/tailcat/tailcat.go`](https://github.com/tailscale/tailcat/blob/main/cmd/tailcat/tailcat.go) (lines 56-68), calls `ParseConnBlobRaw` internally and outputs the CBOR contents as formatted JSON to stdout, making it ideal for quick inspection without writing code.

### What information is contained in a decoded Tailcat token?

Decoded tokens contain a **ServerPublic** key structure, **Region** arrays with DERP node details (including names, hostnames, and keys), and **RegionID** routing information. The exact fields available depend on whether you use raw parsing or full parsing with field restoration via `ParseConnBlob`.