mythik-cli

The command-line and programmatic surface for operating Mythik contracts. mythik and mythik-cli/api are how an AI agent — or a human — reads structure, applies validated patches, moves environment pointers, queries history, and asks a running app for Reveal context.

See the framework README on GitHub for the full Mythik architecture and design philosophy. This file documents what mythik-cli gives you and how to use it.

What Mythik is, briefly

Mythik is an AI-first JSON-native app framework. Most of your app lives as validated JSON specs loaded at runtime from your database, not source code that must be regenerated and redeployed for every change. AI agents compose those specs from a documented vocabulary; Mythik validates the shape, references, actions, state paths, and cross-contract assumptions before the change reaches runtime. This package is the CLI workflow for reading, patching, validating, versioning, and promoting those contracts.

Install

npm install -D mythik-cli

The package exposes the mythik binary:

npx mythik --help

The canonical workflow

The Mythik loop is not pull/edit/push. A fresh agent first loads the project operating context, then reads only the contract structure it needs, writes a small versioned patch, validates it, and verifies the result.

agent context
     |
     v
manifest -> elements -> patch --from-file --author -> validate -> verify
   ^                         |                         |
   |                         v                         v
   |              structured diagnostics        manifest / elements
   |                                             history / Reveal
   +---------------------- refine and retry ----------------------+

The usual command path:

# 0. Load project-local Mythik instructions and active store context
$ npx mythik agent context --app task-app --include-screens --out .mythik/agent/context.md

# 1. Read structure without dumping the whole spec
$ npx mythik manifest task-manager

# 2. Read just the elements you need (use --toon for token-efficient output)
$ npx mythik elements task-manager task-row,new-task-form --json

# 3. Apply a small patch (validates atomically; rejected if it breaks the contract)
$ npx mythik patch task-manager --from-file add-due-date.json --author claude
OK Patch applied. v3 -> v4. 4 elements modified.

# 4. Validate the stored contract
$ npx mythik validate task-manager

# 5. Verify structurally or with live runtime context
$ npx mythik manifest task-manager
$ npx mythik reveal screen task-manager --app task-app --json

When patch fails (the candidate breaks the contract), the gate returns structured diagnostics: rule IDs, paths, suggestion text. The agent reads the error, refines the patch, and retries. No half-baked write ever lands. When the patch passes, verification can be structural (manifest, elements, history) or live through Reveal when a running app is available.

Agent Context

npx mythik agent init all
npx mythik agent context --app app-demo --include-screens --out .mythik/agent/context.md

agent init codex creates or updates AGENTS.md; agent init claude creates or updates CLAUDE.md; agent init all updates both. Existing agent files are preserved outside the Mythik-managed block delimited by <!-- mythik-agent-protocol:start --> and <!-- mythik-agent-protocol:end -->.

The adapters point agents to shared files under .mythik/agent/ (context.md, protocol.md, commands.md, reveal.md, and safety.md). Agents should read those files before editing specs. The generated protocol keeps existing specs on manifest -> elements -> patch --from-file --author -> validate -> verify, names the active Mythik store as the source of truth, and keeps local drafts from becoming a false source of truth. push is for new specs or intentional full replacement; existing specs require explicit --replace, and persisted writes require --author <name> or an intentional --allow-unversioned.

Mythik Sentinel: CLI guidance for agents

Mythik also coaches the agent from inside the CLI. Sentinel is a best-effort protocol guardrail that watches command intent, not spec contents. On first CLI use in a project it reminds the agent to run mythik agent init codex|claude|all. If it sees repeated full replacement intent (push --replace or push --from-dir --replace) with little or no patch usage, it prints a correction back toward the canonical loop.

Sentinel does not change exit codes and does not store specs, patches, URLs, credentials, or state values. Its small cache only records command counters and warning timestamps. JSON object output may receive protocol.warnings; TOON and other machine-readable outputs are left parseable. Set MYTHIK_SENTINEL=off to suppress advisory warnings in exceptional automation.

For replacement safety, push --replace also skips an identical existing document instead of creating a new version. JSON output reports skipped: true and skipReason: "no-diff" for that no-change path.

Moving across environments

dev, staging, production are not deploy targets — they are pointers to specific versions of a spec. Move them with envs; promote across them atomically with promote:

# Move the dev pointer to the new version
$ npx mythik envs task-manager --set dev=4 --author claude

# Promote dev → production (validates atomically; rejected if inconsistent)
$ npx mythik promote task-manager --from dev --to production --confirm --author mldix
✓ Validated against contract.
✓ Cross-screen consistency check passed.
✓ Pointer moved: production v3 → v4.

# List current environment pointers
$ npx mythik envs task-manager --json

Read-only previews

For drafts and audits outside the canonical loop:

# Validate a stored spec (read-only check; no write)
$ npx mythik validate task-manager

# Lint a local file (draft not yet pushed) or a directory
$ npx mythik lint --from-file draft.json
$ npx mythik lint --from-dir ./specs

# Cross-validate a frontend spec against an ApiSpec (catches drift before deploy)
$ npx mythik contract --app app-demo --api api-demo

All three run the same validators that patch and promote enforce atomically — useful when constructing complex multi-step changes locally before committing to a push.

Mythik Reveal: runtime context for agents

mythik reveal lets the running app explain itself to the AI. It is not another linter. Lint and validate inspect specs before they run; Reveal asks the live app what it mounted, what state it has, which actions fired, which render errors occurred, and which element props resolved at runtime.

Start a local token-protected bridge:

npx mythik reveal start --port 17373

The command prints:

MYTHIK_REVEAL_URL=http://127.0.0.1:17373
MYTHIK_REVEAL_TOKEN=<generated-token>

Pass those values to the reveal config on MythikApp or MythikRenderer in development. Then inspect:

npx mythik reveal apps --json
npx mythik reveal context --app my-app
npx mythik reveal current --app my-app
npx mythik reveal screen dashboard --app my-app
npx mythik reveal element save-button --app my-app

Agents should use Reveal before guessing about runtime behavior. If a button does not fire, a screen renders an unexpected branch, or a data source fails silently, Reveal returns the state, diagnostics, and event trail needed for the next patch.

Security rules:

• Run the bridge locally in development only.
• Never commit MYTHIK_REVEAL_TOKEN.
• Prefer narrow includeStatePaths.
• Redact /auth, /secrets, tokens, passwords, API keys, and session values before exposing context to an agent.

Store backends

The CLI can operate against memory, file, Supabase, SQL Server, PostgreSQL, MySQL, and SQLite stores. SQL stores share the same edit loop: inspect with manifest, read exact nodes with elements, write with patch --from-file, then verify.

# SQLite: local development, demos, tests
npx mythik init-store --dialect sqlite --target ./mythik.db
npx mythik patch floor-editor --from-file patch.json --store sqlite --filename ./mythik.db --author ai-agent

# PostgreSQL
npx mythik init-store --dialect postgres --dry-run
npx mythik patch floor-editor --from-file patch.json --store postgres --url "$DATABASE_URL" --author ai-agent

# MySQL
npx mythik init-store --dialect mysql --dry-run
npx mythik patch floor-editor --from-file patch.json --store mysql --url "$DATABASE_URL" --author ai-agent

# SQL Server
npx mythik init-store --dialect sqlserver --server localhost --database Mythik --user "$DB_USER" --password "$DB_PASSWORD" --encrypt false --trust-server-certificate
npx mythik patch floor-editor --from-file patch.json --store sqlserver --server localhost --database Mythik --user "$DB_USER" --password "$DB_PASSWORD" --author ai-agent

init-store --dry-run prints the idempotent DDL for review or for a team-managed migration pipeline. Runtime reads and writes do not silently create missing store tables. MySQL generated upsert SQL targets MySQL 8.0.19+.

History and rollback

# Show version history with structural diffs
$ npx mythik history task-manager

# Compare two versions or two environments
$ npx mythik diff task-manager 3 4
$ npx mythik diff task-manager dev production

# Always-forward rollback (creates a new version with old content)
$ npx mythik rollback task-manager --to 3 --author mldix

Rollback never rewrites history. The new version v5 will hold the content of v3. v4 stays in the history with its own author and timestamp.

Output formats

| Flag | When to use | |---|---| | --json | Machine-readable output for scripts and IDE integrations | | --toon (where supported) | Token-efficient agent reads — same shape, fewer tokens, useful for paginating large manifests or element catalogs |

Programmatic API

When a script, IDE integration, or AI agent should avoid shell quoting, use mythik-cli/api:

import { readFile } from 'node:fs/promises';
import { parsePatchInput, runPatch } from 'mythik-cli/api';

const patches = parsePatchInput(await readFile('add-due-date.json', 'utf8'));
const result = await runPatch('task-manager', patches, {
  store,
  author: 'claude',
  json: true,
});

if (result.exitCode !== 0) {
  console.error(result.output);
}

The programmatic API uses the same implementation path as the binary — nothing is special-cased. Whatever the CLI does, the API does identically.

Bundled AI documentation

The mythik package (peer dependency) ships canonical AI docs at node_modules/mythik/docs/. Locate or copy them:

$ npx mythik docs path
/your-project/node_modules/mythik/docs

$ npx mythik docs copy ./mythik-docs

Point your AI agent at the printed path before asking it to author or modify specs. Inside that directory:

• consumer/ai-context.md — spec-generation primer (rules and traps)
• consumer/ai-context-primitives.md — every primitive's props
• consumer/reference-doc.md — full rule catalog
• wiki/compiled/ — atomic per-concept articles (one page per action, primitive, rule, expression) optimized for AI lookup
• llms.txt — index for AI tools that read it

Related packages

• mythik — the runtime this CLI manipulates
• mythik-react — render the specs as a React app
• mythik-server — declarative REST server from an ApiSpec
• mythik-react-native — render supported Mythik primitives in Expo and React Native

Status

Public release line. The binary name is mythik; the npm package name is mythik-cli. APIs are documented for real-world feedback as the framework evolves.

Releases

Release notes and patch details are published in the CHANGELOG and on GitHub Releases.

License

Apache-2.0.