description: "Command-line interface for Telo kernel: loads and runs YAML manifests locally with watch mode and module publishing"

Telo CLI

The Telo CLI is the command-line interface for the Telo kernel. It loads YAML manifests and runs them on your local machine.

Installation

npm install -g @telorun/cli
# or
pnpm add -g @telorun/cli

Quick Start

# Run a local manifest
telo ./examples/hello-api.yaml

# Run from a remote URL
telo https://raw.githubusercontent.com/telorun/telo/main/examples/hello-api.yaml

# Watch mode - auto-restart on file changes
telo --watch ./manifest.yaml

Commands

telo publish <paths..>

Publish one or more module manifests to the Telo registry. For each manifest, the command:

1. Finds all controllers entries with a local_path qualifier (i.e. locally-developed packages).
2. Optionally bumps each controller package version with --bump.
3. Builds each controller package.
4. Publishes each controller package to its registry (currently npm). If the version already exists, the publish step is skipped — the command is idempotent.
5. Rewrites the PURL version specs in the manifest to exact static versions.
6. Bumps metadata.version in the manifest when --bump is given.
7. Pushes the updated manifest to the Telo registry.

telo publish ./modules/my-module/telo.yaml
telo publish ./modules/my-module/telo.yaml --bump=patch
telo publish ./modules/a/telo.yaml ./modules/b/telo.yaml --bump=minor
telo publish ./modules/my-module/telo.yaml --dry-run
telo publish ./modules/my-module/telo.yaml --skip-controllers

Options:

• --bump patch|minor|major — Bump all controller package versions before publishing. Also bumps metadata.version in the manifest.
• --registry <url> — Telo registry base URL (default: https://registry.telo.run)
• --dry-run — Show what would happen without writing files or publishing anything.
• --skip-controllers — Skip the controller build/publish/PURL-rewrite loop and only run static analysis and push the manifest to the Telo registry. Use this when controller packages have already been published by another tool (e.g. Changesets in CI). Mutually exclusive with --bump.

Environment:

• TELO_REGISTRY_TOKEN — Bearer token for the registry's publish endpoint. The CLI adds it as Authorization: Bearer <token> on each PUT; without it, the server returns 401. Operators receive a token from whoever administers the registry (see apps/registry/README.md for provisioning). Example:

  TELO_REGISTRY_TOKEN=<token> telo publish ./modules/my-module/telo.yaml

Example output:

Publishing modules/run/telo.yaml

  @telorun/run
    bump     0.1.1 → 0.1.2
    build    ✓
    publish  ✓  @telorun/[email protected]
    purl     @0.1.1 → @0.1.2

  manifest
    version  0.1.0 → 0.1.1
    push     ✓  std/[email protected] → https://registry.telo.run/std/run/0.1.1

telo check <paths..>

Statically validates one or more manifests without running them. Uses the Telo analyzer to check schema correctness, x-telo-ref references, CEL expression types, and resource scope visibility. Exits with code 1 if any errors are found.

telo check ./manifest.yaml
telo check ./modules/my-module/telo.yaml
telo check https://example.com/manifest.yaml

Accepts local paths, directories containing a telo.yaml, or HTTP(S) URLs.

Example output:

manifest.yaml:14:5  error    Unknown resource kind "Http.Srver"  E001
manifest.yaml:22:7  warning  Unused variable "port"  W003

2 errors, 1 warning

On success:

✓  No issues found

telo install <paths..>

Pre-downloads every controller declared by a manifest and its transitive Telo.Imports into the on-disk cache. At runtime the kernel finds each controller already installed and skips the boot-time npm install — removing the startup delay and the network dependency from production deployments.

Installs run in parallel; failures are reported per controller and the command exits non-zero if any failed. Subsequent runs are idempotent — already-cached packages are skipped.

telo install ./apps/my-app/telo.yaml
telo install ./apps/a/telo.yaml ./apps/b/telo.yaml

Environment:

• TELO_CACHE_DIR — Absolute path to the on-disk cache root. Defaults to ~/.cache/telo (shared across projects for a user). Override to pin the cache alongside the manifest when producing a self-contained bundle (e.g. a Docker image). The kernel at boot reads from the same variable, so set it in both the install step and the runtime environment.

Example output:

Installing 20 controllers for apps/my-app/telo.yaml
  ✓  pkg:npm/@telorun/[email protected]?local_path=./nodejs#http-server
  ✓  pkg:npm/@telorun/[email protected]?local_path=./nodejs#http-client
  ...

✓  20 installed in 3.2s

Typical Dockerfile usage:

FROM telorun/telo:nodejs as build
WORKDIR /srv
ENV TELO_CACHE_DIR=/srv/.telo-cache
COPY apps/my-app/telo.yaml apps/my-app/telo.yaml
COPY modules/ modules/
RUN telo install apps/my-app/telo.yaml

FROM telorun/telo:nodejs as production
WORKDIR /srv
ENV TELO_CACHE_DIR=/srv/.telo-cache
COPY --from=build /srv /srv
CMD ["apps/my-app/telo.yaml"]

The build stage populates the cache; the production stage is a single COPY and does no network I/O at boot.

telo [manifest]

Load and run a Telo manifest.

Arguments:

• manifest - Path to a YAML manifest file or directory. Can be local or a remote URL.

Options:

• --watch, -w - Watch manifest file(s) for changes and restart automatically
• --verbose, -v - Enable verbose logging
• --help, -h - Show help message
• --version - Show version number

Examples

Simple HTTP Server

Create a file server.yaml:

kind: Telo.Application
metadata:
  name: Example
targets:
  - Server
---
kind: Telo.Import
metadata:
  name: HttpServer
source: std/[email protected]
---
kind: Telo.Import
metadata:
  name: JavaScript
source: std/[email protected]
---
kind: Http.Server
metadata:
  name: Server
  module: Example
baseUrl: http://localhost:8080
port: 8080
mounts:
  - path: /api
    type: Http.Api.HelloApi
---
kind: Http.Api
metadata:
  name: HelloApi
  module: Example
routes:
  - request:
      path: /hello
      method: GET
    handler:
      kind: JavaScript.Script
      code: |
        function main() {
          return { message: 'Hello World!' }
        }
    response:
      status: 200
      statuses:
        200:
          body:
            message: "${{ result.message }}"

Run it:

telo server.yaml

Access it at http://localhost:8080/api/hello

Watch Mode for Development

telo --watch ./manifest.yaml

In watch mode, the manifest is reloaded and the kernel restarted whenever any manifest files change. This is useful while developing.

Remote Manifests

You can run manifests directly from URLs without downloading them:

telo https://example.com/my-manifest.yaml

Status

The CLI is part of the Telo project and follows the same early prototype status. The command-line interface and behavior may change.

See Also

• Telo Kernel - Core concepts and resource types
• Modules - Available built-in modules