---
title: Name Service
description: Manage base name service registrars, subdomains, and records with thru
source_url:
  html: https://thru.org/docs/cli-reference/name-service-commands/
  md: https://thru.org/docs/cli-reference/name-service-commands.md
---

# Name Service

> For registry pricing and lease lifecycle (initialize registry, purchase, renew, claim expired), use the [`registrar` commands](https://thru.org/docs/cli-reference/registrar-commands.md).

## Prerequisites

- [CLI setup](https://thru.org/docs/program-development/setting-up-thru-devkit.md) with keys and RPC endpoint configured
- Name service program ID available (defaults to config value)
- Fee payer funded for signer costs

## Command Overview

- [Init Root Registrar](#init-root-registrar): Create a base registrar for a root name
- [Register Subdomain](#register-subdomain): Add subdomains under a registrar or domain
- [Manage Records](#manage-records): Append or delete key/value records on a domain
- [Unregister Subdomain](#unregister-subdomain): Remove a subdomain under a registrar or domain
- [Resolve & List](#resolve-and-list): Read domain metadata and records
- [Derive Addresses](#derive-addresses): Calculate registrar, domain, lease, and config addresses

## Init Root Registrar

Set up a base registrar on the name service program for a root (for example, `thru`). The registrar address can be derived automatically from the root name.

```bash
thru nameservice init-root $root_name [OPTIONS]
```

**`root_name` · *string* · **required****

Root segment to manage (1-64 characters)

***string***

Override base name service program address

***string***

Explicit registrar account address; derived from the root name if omitted

***string***

Authority address for root management, formatted as a 46-char `ta...` address or 64-char hex pubkey. Key names are not accepted. Must match the fee payer address because only the fee payer signature is included.

***string***

Hex state proof for registrar account creation; auto-generated if omitted

***string***

Signer for the transaction

**Example:**

```bash
thru nameservice init-root thru
```

## Register Subdomain

Create a subdomain under a parent registrar or domain. The CLI can derive the domain account address from the parent and name.

```bash
thru nameservice register-subdomain \
  $domain_name \
  $parent_account \
  [OPTIONS]
```

**`domain_name` · *string* · **required****

Subdomain segment (1-64 characters)

**`parent_account` · *string* · **required****

Registrar or parent domain address

***string***

Override base name service program address

***string***

Explicit domain account address; derived if omitted

***string***

Domain owner address, formatted as a 46-char `ta...` address or 64-char hex pubkey. Key names are not accepted. Must match the fee payer address because only the fee payer signature is included.

***string***

Authority address for subdomain registration, formatted as a 46-char `ta...` address or 64-char hex pubkey. Key names are not accepted. Must match the fee payer address because only the fee payer signature is included.

***string***

Hex state proof for domain creation; auto-generated if omitted

***string***

Signer for the transaction

## Manage Records

Append or delete records on a domain.

```bash
thru nameservice append-record \
  $domain_account \
  $key \
  $value \
  [--owner $owner] [--fee-payer $fee_payer] [--name-service-program $program]

thru nameservice delete-record \
  $domain_account \
  $key \
  [--owner $owner] [--fee-payer $fee_payer] [--name-service-program $program]
```

**`domain_account` · *string* · **required****

Domain account address

**`key` · *string* · **required****

Record key (<= 32 bytes)

**`value` · *string* · **required****

Record value (<= 256 bytes) for append-record

***string***

Owner address authorizing the record change, formatted as a 46-char `ta...` address or 64-char hex pubkey. Key names are not accepted. Must match the fee payer address because only the fee payer signature is included.

***string***

Signer for the transaction

***string***

Override base name service program address

## Unregister Subdomain

Delete a subdomain under a registrar or domain.

```bash
thru nameservice unregister-subdomain \
  $domain_account \
  [--owner $owner] [--fee-payer $fee_payer] [--name-service-program $program]
```

**`domain_account` · *string* · **required****

Domain account address to remove

***string***

Owner address authorizing unregister, formatted as a 46-char `ta...` address or 64-char hex pubkey. Key names are not accepted. Must match the fee payer address because only the fee payer signature is included.

***string***

Signer for the transaction

***string***

Override base name service program address

## Resolve and List

Fetch domain metadata and records.

```bash
thru nameservice resolve $domain_account [--key $key] [--name-service-program $program]
thru nameservice list-records $domain_account [--name-service-program $program]
```

**`domain_account` · *string* · **required****

Domain account to inspect

***string***

Record key to fetch when resolving

***string***

Override base name service program address

## Derive Addresses

Helpers to compute deterministic addresses.

```bash
thru nameservice derive-domain-account $parent_account $domain_name [--name-service-program $program]
thru nameservice derive-registrar-account $root_name [--name-service-program $program]
thru nameservice derive-config-account [--thru-registrar-program $program]
thru nameservice derive-lease-account $domain_name [--thru-registrar-program $program]
```

**`parent_account` · *string* · **required****

Registrar or parent domain address for domain derivation

**`domain_name` · *string* · **required****

Domain segment (1-64 characters)

**`root_name` · *string* · **required****

Root segment (for registrar derivation)

***string***

Override base name service program address for `derive-domain-account` and `derive-registrar-account`

***string***

Override thru registrar program address for `derive-config-account` and `derive-lease-account`

## Common Flow

1. Use `thru registrar initialize-registry` and `purchase-domain` to create a .thru lease (see [Registrar Commands](https://thru.org/docs/cli-reference/registrar-commands.md)).
2. (Optional) Register subdomains with `thru nameservice register-subdomain`.
3. Manage and query records with `append-record`, `delete-record`, `resolve`, and `list-records`.