Offline SEP-1 validation

Catch Stellar info file issues before you deploy.

stellar-toml-lint reads your local stellar.toml or a live domain and reports rule violations with file/line references, severity levels, and spec links.

npm package Project README

Node.js 20+
MIT/Apache-2.0 package license
Works in CI, pre-commit, and local dev

$ npx stellar-toml-lint public/.well-known/stellar.toml

public/.well-known/stellar.toml
  12:1      error    NETWORK_PASSPHRASE has stray whitespace
  31:1      error    CURRENCIES[0].issuer is not a valid Stellar account ID
  34:1      error    issuance policies are mutually exclusive
  19:1      warning  DOCUMENTATION.ORG_PHONE_NUMBER is not in E.164 format

  4 problems (3 errors, 1 warning, 0 infos)

In-browser validation

Try a stellar.toml

Linting runs locally in your browser. Share the URL to send someone the current TOML.

stellar.toml editor

Changes are linted as you type.

Diagnostics

Why this exists

It closes the gap between local validation and live deployment.

Local-first linting

The project validates a file before it is deployed, instead of waiting for a live domain to fail in production.

SEP-1 and Stellar checks

It validates checksum correctness, URL formats, field constraints, network passphrases, policy combinations, and more.

CI-friendly output

It supports text, JSON, SARIF, and GitHub workflow annotations so the output works in pull requests and security tooling.

Compared with live-only testing

Capability	stellar-toml-lint	@stellar/anchor-tests
Lints a local file	✅	❌
Needs a deployed domain	❌	✅
Line and column diagnostics	✅	❌
Validates key checksums	✅	Partial
Live SEP-6/10/24/31 flow checks	❌	✅

What it checks

It covers the major rules and validation categories in SEP-1.

File

Files under the size limit, TOML parsing, line/column diagnostics, UTF-8 BOM detection.

General

Version fields, network passphrases, URL constraints, checksum validation, deprecated and unknown fields.

[DOCUMENTATION]

Required organization metadata, URL/domain consistency, email, phone, and social handle validation.

[[PRINCIPALS]]

Name/email validation and hash plausibility for principal profile photos.

[[CURRENCIES]]

Asset code rules, issuance policies, anchored asset metadata, collateral validation, duplicate asset checks.

[[VALIDATORS]]

Alias format, unique keys and hosts, port checks, and history URL validation.

Network checks

With --domain, it verifies reachability, CORS headers, content type, file size, and the negotiated TLS session — deprecated protocol versions and weak cipher suites included.

Usage

Run it locally or against a deployed domain.

# Lint a local file
stellar-toml-lint public/.well-known/stellar.toml

# Fetch and lint a live site
stellar-toml-lint --domain example.com

# Read from stdin
cat stellar.toml | stellar-toml-lint -

Common flags

-d, --domain <d> — serve from a domain for CORS, TLS, and same-domain checks
-f, --format <fmt> — text, json, ndjson, sarif, github, junit, checkstyle
--strict — treat warnings like errors
--show-help-urls — include spec links for each finding
--list-rules — show every built-in rule

Programmatic API

Use the library directly inside Node.js and CI jobs.

import { lint, lintDomain, formatText } from 'stellar-toml-lint';
import { readFile } from 'node:fs/promises';

const result = lint(await readFile('stellar.toml', 'utf8'), {
  domain: 'example.com',
  strict: true,
  rules: { 'general/unknown-field': 'off' },
});

if (!result.ok) {
  console.error(formatText(result, { color: true }));
  process.exit(1);
}

const live = await lintDomain('example.com');

CI and automation

Integrate it anywhere a release is checked.

GitHub Action

- uses: anchor-tools/stellar-toml-lint@v1
  with:
    file: public/.well-known/stellar.toml
    strict: true

Pre-commit

repos:
  - repo: local
    hooks:
      - id: stellar-toml-lint
        entry: npx stellar-toml-lint
        language: system

Severity model

Error — violates SEP-1 or breaks client compatibility.

Warning — valid but incomplete or likely wrong.

Info — worth reviewing, often unknown field names.