@intentic/cli

The intentic command: tunnels, deployment and scaffolding, in one toolbox.

Three command groups: tunnel (the sandbox's own Cloudflare tunnels, used by connect.sh), deploy (the bundled deployment engine: turn a local intent file into a desired-state artifact and reconcile it, no remote control plane required), and scaffold (seed app repos). The deploy group depends on @intentic/engine, @intentic/providers, @intentic/need-resolver, @intentic/state-resolver, @intentic/graph.

Local control plane

The "control plane" is two local git repos: an intent repo holding deploy.config.ts, and a desired-state repo holding the generated artifact (desired-state.json) and the execution record (status.json). intentic deploy init scaffolds both.

Commands

Built on stricli with generated --help / --version.

• intentic deploy init [--dir .]: scaffold the intent and desired-state git repos (intent seeded with a starter deploy.config.ts).
• intentic deploy resolve [--config deploy.config.ts] [--out desired-state.json]: load the intent, resolve it to a DesiredStateGraph, and write it, along with .env.example (the user-supplied secrets) and .secrets.json (the intentic-generated ones). No infra access.
• intentic deploy plan [--artifact desired-state.json]: read-only preview of what apply would create/update.
• intentic deploy apply [--artifact desired-state.json] [--max-iterations 5]: reconcile the artifact until state reads true, writing status.json beside it. Reads user-supplied secrets from .env beside the artifact (or the environment) and generates the platform admin secrets it owns (see below). On success it prints an Access summary and writes access.md beside the artifact: the URL, the intentic username, and the password (the generated value on stdout; a pointer to .secrets.json in the committed access.md) for Forgejo and Komodo, plus each app-environment URL.

Secrets

Secrets split by who provides them:

• User-supplied (source: env), credentials to systems intentic does not create: HOST_SSH_KEY, CLOUDFLARE_API_TOKEN, and each environment's *_DATABASE_URL. You set these in .env beside the artifact (or the ambient environment). The required set is more than what your deploy.config.ts names, so resolve derives it from the graph and writes desired-state/.env.example.
• intentic-generated (source: generated), admin credentials for the services intentic itself provisions: FORGEJO_ADMIN_PASSWORD, KOMODO_ADMIN_PASSWORD, KOMODO_WEBHOOK_SECRET. resolve generates each one (shell-safe hex) the first time and persists it to gitignored desired-state/.secrets.json, reusing it forever after (plan/apply reuse it too; Forgejo/Komodo bake the password in on first init and won't re-key, so it must be stable). intentic owns this file: it's authoritative, so put platform keys here, not in .env; to pin your own value, edit .secrets.json. The Forgejo/Komodo password is what you log in with, as user intentic.

Both .env and .secrets.json are gitignored, so no secret lands in the PR-managed repo.

Workflow

intentic deploy init
cd intent && intentic deploy resolve --out ../desired-state/desired-state.json
cp ../desired-state/.env.example ../desired-state/.env   # fill in the user-supplied values resolve listed
cd .. && intentic deploy apply                                  # generates the platform secrets, prints the logins

A deploy.config.ts imports @intentic/sdk + @intentic/graph, so the project it lives in must have them installed. apply reconciles the per-host platform (Forgejo/Komodo/runner, Cloudflare tunnel + DNS) as ordinary nodes in the artifact: a future "PR-managed" phase (a remote Forgejo watching the intent repo) would layer on top of this same flow.

Key files

• src/cli.ts / src/app.ts: the stricli app and command wiring.
• src/init/init.ts / src/resolve/resolve.ts / src/apply/apply.command.ts: the init/resolve/apply commands (plan lives alongside resolve/apply).
• src/lib/artifact.ts: readArtifact/writeArtifact/writeStatus (the desired-state files).
• src/lib/output.ts: honors INTENTIC_OUTPUT (text/json/ndjson); maps EngineEvents to the chosen format.
• src/adopt/adopt.ts: push the intent/desired-state repos into Forgejo + wire Actions.
• src/apply/access.ts: the post-apply Access summary + access.md; src/lib/known-hosts.ts, TOFU host-key pinning.

Conventions

• Runs the engine as the only place providers are constructed (via createProviders); it owns reading .env and generating .secrets.json.
• Subprocess-friendly: a backend can drive it and parse INTENTIC_OUTPUT=ndjson/json instead of scraping prose (the platform's provision.ts does exactly this).
• Co-located unit tests + a gated src/cli.e2e.test.ts (real infra, opt-in).

Key exports: loadIntent; readArtifact / writeArtifact / writeStatus; scaffold; the CONFIG_FILE / ARTIFACT_FILE / STATUS_FILE constants. See ARCHITECTURE.md.