lekton-sync

CLI tool to sync markdown documents, prompt definitions, and schema artifacts to a Lekton instance.

It scans a directory for .md files, prompt YAML files, and schema manifests, calls the Lekton sync APIs to compute the delta, and uploads only the content that has changed.

Installation

cargo install lekton-sync

Docker

Build the default minimal container image from the repository root:

docker build -f cli/Dockerfile -t lekton-sync .

Build a Jenkins-friendly variant with a debian:bookworm-slim runtime:

docker build -f cli/Dockerfile --target ci -t lekton-sync-ci .

Run it by mounting the documentation workspace and passing the usual environment variables:

docker run --rm \
  -e LEKTON_URL=https://lekton.example.com \
  -e LEKTON_TOKEN=your-service-token \
  -v "$PWD:/workspace" \
  lekton-sync /workspace

This image contains only the lekton-sync binary in a distroless runtime, so it fits well in documentation CI pipelines without installing Rust toolchains on the runner.

When you need a shell-capable image for CI systems that keep sidecars alive with commands such as sleep infinity, use the ci target instead. It ships the same lekton-sync binary on top of debian:bookworm-slim.

Tagged releases can also publish a ready-to-use Docker image via GitHub Actions:

docker run --rm \
  -e LEKTON_URL=https://lekton.example.com \
  -e LEKTON_TOKEN=your-service-token \
  -v "$PWD:/workspace" \
  docker.io/<your-dockerhub-namespace>/lekton-sync:0.13.0 /workspace

The publish workflow also builds a companion lekton-sync-ci image for Jenkins/Kubernetes-style runners.

Usage

lekton-sync [OPTIONS] [ROOT]

Environment variables

*Can also be set via url in .lekton.yml.

Document format

Each markdown file must have a YAML front matter block. Files without front matter are skipped.

---
title: My Document
slug: optional/custom-slug        # defaults to file path relative to root
access_level: public               # defaults to "public"
service_owner: my-team             # optional
tags: [guide, onboarding]          # optional
order: 10                          # optional, for ordering within a section
is_hidden: false                   # optional
---

Document body...

The slug is derived from the file path relative to the root directory (e.g. docs/guides/intro.md → docs/guides/intro), unless overridden by the slug field in the front matter.

Prompt format

Prompt definitions are loaded from prompts/*.yaml by default. This directory can be changed via .lekton.yml.

name: Code Review
description: Review a patch before merge
owner: platform-team
access_level: developer
status: active
publish_to_mcp: true
default_primary: true
context_cost: medium
tags: [engineering, review]
variables:
  - name: diff
    description: Unified diff to inspect
    required: true
prompt_body: |
  Review the following diff:
  {{diff}}

Supported prompt fields:

The prompt slug is derived from the path relative to the prompt directory and prefixed with prompts/ by default (for example prompts/code-review.yaml → prompts/code-review).

Configuration file

Place a .lekton.yml file in the root directory (or pass --config) to set project-level defaults:

url: https://lekton.example.com
default_access_level: internal
default_service_owner: platform-team
slug_prefix: protocols/my-service
prompts_dir: prompts
prompt_slug_prefix: prompts
archive_missing: false

Schema format

Schema versions are discovered from lekton.schema.yml manifests under schemas/ by default.

name: payment-api
schema_type: openapi
service_owner: payments
default_access_level: internal
tags: [payments, api]
versions:
  - file: openapi-v1.yaml
    version: 1.0.0
    status: deprecated
    access_level: public
  - file: openapi-v2.yaml
    version: 2.0.0
    status: stable

Supported manifest fields:

The CLI computes separate content and metadata hashes for each schema version, calls POST /api/v1/schemas/sync, and uploads only new or changed versions.

Example

export LEKTON_TOKEN=my-service-token
export LEKTON_URL=https://lekton.example.com

# Preview what would change
lekton-sync --dry-run ./docs

# Sync and archive documents/prompts no longer present locally
lekton-sync --archive-missing ./docs

GitHub Actions example

- name: Sync docs to Lekton
  run: |
    docker run --rm \
      -e LEKTON_URL="${{ secrets.LEKTON_URL }}" \
      -e LEKTON_TOKEN="${{ secrets.LEKTON_TOKEN }}" \
      -v "${{ github.workspace }}:/workspace" \
      docker.io/${{ secrets.DOCKERHUB_USERNAME }}/lekton-sync:${{ github.ref_name }} \
      --archive-missing /workspace/docs

License

AGPL-3.0