Permalink to Run Source & BuildsRun Source & Builds

The Author Source defines the video. A Run Source chooses which of its public outputs to produce and which explicit Candidates, if any, should satisfy them. The official Distribution supplies the Local Runtime; its Profile names the credentials, Provider Endpoints and services available to execute the resulting plan.

Select the project Runtime once:

hypit runtime use hypit.runtime.json

Ordinary work then follows the short path:

hypit plan build.svrun
hypit build build.svrun --follow
hypit get <build-id> --output final.video --to output/final.mp4

The Quickstart installs the Distribution once. Every command on this page then works as hypit from any independent video project.

Only build submits work. plan shows the selected work. check is an editing aid; doctor is a deployment diagnostic. They are safe to run, but not mandatory ceremony before every Build.

One convenient layout for a project with several Author, Recipe and Run Sources is:

my-video/
  package.json              project boundary
  authors/
    main.svml               one Author entry
    alternate.svml          another Author entry, when genuinely needed
  recipes/
    visual.svs              authored visual Recipes
    generation.svs          authored generation Recipes
  runs/
    images.svrun            one executable intention
    takes.svrun             another executable intention
    final.svrun             final delivery intention
  assets/                   project-owned input media
  kits/                     optional project-authored Recipe Kits
  packages/                 project-local Author packages when the work introduces them
  output/                   explicit exports for people and other tools
  hypit.runtime.json        execution environment
  hypit.results.json        optional Result repository selection
  .hypit/                   generated local Runtime and Result data

This layout is only a human-facing recommendation, never a required project schema. A small project may keep several .svml, .svs and .svrun files flat at its root, and another project may group them differently. Hypit uses only the paths written in Source imports, <author source="…">, CLI arguments and get --to; it does not require these names or recognize authors/, recipes/, runs/, assets/ or output/ specially. Each Run selects one Author entry, while that Author Source closure may explicitly import multiple Author or Recipe Sources. The managed Result repository remains separate under .hypit/results by default.

Run Source and Runtime Profile do not silently rewrite the video. Creative model choices remain in the Author Source or in packages that it explicitly imports.

Permalink to run-source-syntaxRun Source syntax

Every .svrun file begins with its processing instruction:

<?svml using="@hypit/run-markup@1"?>

Permalink to minimal-run-sourceMinimal Run Source

<?svml using="@hypit/run-markup@1"?>

<svrun version="1">
  <author source="./main.svml"/>
  <target output="final.video"/>
</svrun>

Permalink to targetsTargets

A Target is the Build's final intention, normally the finished video or another real deliverable. It is not a retention list. The compiler executes only the route needed for the Targets, and every public Author Output that actually completes on that route is written into the same Build Result. Internal Operation values remain execution details.

Permalink to multiple-targetsMultiple targets

You can demand multiple outputs from one Build:

<target output="final.video"/>
<target output="captions.track"/>

Use multiple Targets only when one execution genuinely has several final goals. Different build intentions should be separate .svrun files. They can point to the same Author Source without duplicating it.

Permalink to reusing-resultsReusing results

Hypit has no implicit cache. Reusing a result is explicit Run Graph authoring — you declare one named Output from one earlier Build Result as a zero-input Candidate and connect it through a Satisfaction edge.

As soon as a generated image or take is accepted, reuse it explicitly in the next .svrun with build-record and satisfy, then inspect the plan before starting paid downstream work.

<?svml using="@hypit/run-markup@1"?>

<svrun version="1">
  <author source="./main.svml"/>
  <target output="final.video"/>

  <build-record id="hook-video"
    build="bld_20260902T142031123Z_0123456789" output="hook-take.video"/>
  <build-record id="meeting-video"
    build="bld_20260902T142031123Z_0123456789" output="meeting-take.video"/>
  <build-record id="evidence-video"
    build="bld_20260902T142031123Z_0123456789" output="evidence-take.video"/>
  <build-record id="payoff-video"
    build="bld_20260902T142031123Z_0123456789" output="payoff-take.video"/>

  <satisfy output="hook-take.video" candidate="hook-video"/>
  <satisfy output="meeting-take.video" candidate="meeting-video"/>
  <satisfy output="evidence-take.video" candidate="evidence-video"/>
  <satisfy output="payoff-take.video" candidate="payoff-video"/>
</svrun>

Permalink to finding-reusable-outputFinding reusable output

Query an output name across the project's local Build Results:

hypit history hook-take.video

history reports only the exact public Author Output requested. It does not list declared-but-unbuilt outputs or internal Operation values. If the old name is unknown, browse Builds and inspect the likely Result:

hypit builds
hypit inspect <build-id>

An output name is a human locator inside one Build Result. The pair build + output is the exact address. If the current source renames hook-take.video to opening-shot.video, keep the old name on <build-record> and use the current name on <satisfy>:

<build-record id="approved-opening"
  build="bld_20260902T110000001Z_0000000001" output="hook-take.video"/>
<satisfy output="opening-shot.video" candidate="approved-opening"/>

Hypit never infers that two names mean the same author intent. Every build invocation receives a fresh Build id and its own Result directory, even when nothing changed. A later Run reuses an Output only by naming the earlier Build id and Output here. If that earlier Output already forwards to an older one, Result storage resolves that explicit path once and records the new Forward directly to the finished Result that owns the value; no bytes are copied and no reverse index is maintained. Forwarding applies only to a complete public Output. Structured JSON cannot recursively point at another Output; a historical value consumed inside a new Fragment is an ordinary input and the new Fragment's Output belongs to the current Result.

Permalink to build-recordbuild-record

Declares a zero-input Candidate backed by one named Output from a previous Build Result:

Permalink to satisfysatisfy

Connects a Candidate to a Logical Output:

The Planner reads the complete Author Graph and Run Graph together. It prunes default Operations that selected Candidates replace while retaining any Author Outputs the selected Candidate itself still consumes. This is a new Build, not a continuation of the old one. Downstream processing (normalization, WhisperX, captioning, rendering) still runs against the reused media.

Core does not label a Candidate as “exact” or “substitute”. Choosing a Candidate is the Run author's explicit implementation decision for that Build. Type compatibility is checked; creative equivalence is neither guessed nor carried as redundant metadata through the graph.

Permalink to using-an-existing-fileUsing an existing file

A local file is the simplest zero-input Candidate. The Run Source names the bytes and connects them to one current Logical Output:

<file id="approved-opening" type="@hypit/artifact@1#BlobArtifact" from="./approved-opening.mp4" media-type="video/mp4"/>
<satisfy output="opening-shot.video" candidate="approved-opening"/>

The file is read relative to the .svrun. If it becomes a completed public Output on the Target route, it is written into the Build Result like any generated media. There is no hidden history lookup. A supplied image, recorded video or other compatible result uses the same mechanism.

Permalink to runtime-profileRuntime Profile

The official video Distribution has already chosen the Local Runtime. Its Profile names the Credential Stores and Endpoints that local execution may use, together with deployment settings such as Endpoint capacity. It never selects the Runtime Host or defines the Source Workspace, Author packages or project Result repository.

hypit runtime init
hypit paths

runtime init writes the video Distribution's starter hypit.runtime.json and selects it. It refuses to overwrite an existing file, installs nothing, contacts no service and starts no Worker. For an existing intentional Profile, use hypit runtime use <profile>; that command writes only .hypit/runtime. See Runtime for the Profile schema and boundaries. The CLI resolves the project first: --workspace is an explicit boundary; otherwise the nearest package.json above the current directory is the boundary, falling back to the current directory for a plain creative folder. It then reads only that project's .hypit/runtime. It never discovers a Profile from a conventional filename or inherits another project's selection from a parent directory.

Permalink to configure-selected-credentialsConfigure selected credentials

check and plan never make live Provider requests. A graph-only plan without a selected Runtime needs no deployment credentials; with a selected Runtime, its cheap preflight checks that demanded credential references are present. Before doctor or a paid/external build, configure only the credentials referenced by the selected Runtime Profile. First inspect the existing selection:

hypit auth status

If a needed service is not ready, choose whether to configure that service or another supported local or hosted option. For example, WhisperX can run locally or through HypiHub. A starter Endpoint is a configuration starting point, not evidence that an account was chosen.

After choosing a service, connect its credential:

Run only the lines for the Endpoints in your Profile. In macOS/Linux shells:

read -r -s KIE_API_KEY
export KIE_API_KEY
read -r -s MIMO_API_KEY
export MIMO_API_KEY

In Windows PowerShell:

$env:KIE_API_KEY = "your-key"
$env:MIMO_API_KEY = "your-key"

Keep credentials out of Author Source, Run Source, Runtime Profile source, and committed files. doctor validates required credential presence without printing secret values.

Permalink to read-prices-for-the-selected-runRead prices for the selected Run

hypit pricing reference.svrun
hypit pricing reference.svrun --json

The selected Runtime determines which Endpoint serves each request. pricing reads those Providers' rate information and groups matching requests, showing known parameters and request counts. Work explicitly declared local without a Provider charge is summarized; unknown prices, unsupported requests and failed price reads remain visible. --verbose includes the local request details and original pricing documents.

Use the report to explain the intended spend: the chosen account, planned material, published units and applicable rates. The command reads prices; it does not submit generation or calculate a guaranteed total. A future media input may not yet have a known duration, so preserve that uncertainty in the estimate. JSON keeps request parameters in groups[].requests and source material in groups[].pricingDocuments.

Agree on the account, work and budget before paid calls. Existing authorization covers the work within that agreement; pricing output and successful authentication are information, not approval.

Permalink to build-workflowBuild workflow

Keep credentials, generated media, Runtime data and logs out of commits. A project may live anywhere:

cd /work/my-film
hypit runtime use hypit.runtime.json

The Workspace is resolved before the Runtime Profile. Override it explicitly with --workspace; the entry Source path and Runtime selection never choose it. --package-root locates installed packages and never widens Source access. --asset-root grants read access to additional asset bytes without permitting Source imports there.

.hypit/
  results/
    <UTC-date>/
      <build-id>/
        result.json
        files/
        values/

That is the zero-configuration Result repository. The output/ directory shown earlier is only a convenient destination for explicit exports and is not part of Result storage. A project-owned hypit.results.json may instead select @hypit/build-result-s3; commands and historical build-record references then use that same repository. Temporary Resources remain local and private to the active Runtime.

Permalink to 1-select-a-runtime1. Select a Runtime

cd examples/podcast
hypit runtime use hypit.runtime.json

Author and Run Sources select their packages through imports. The Local Runtime Profile selects Credential Store and Endpoint packages through use; the project separately owns its Result repository. The installed package manager owns their versions.

Permalink to 2-diagnose-the-environment2. Diagnose the environment

hypit doctor

Doctor always validates the project's selected Result Repository. When a Runtime Profile is selected or passed explicitly, it also validates every selected Runtime role, Endpoint configuration, credential presence and bounded environment probe. It never starts the Worker or performs a paid request.

When a Profile is present, Doctor intentionally performs a full profile audit. For the environment required by one Run, use plan: it checks only capabilities demanded by that finite plan. Missing readiness is returned in preflight and gives the command a non-zero exit status, while the frozen plan remains available in JSON for inspection.

Permalink to 3-check-source-and-inspect-the-plan3. Check source and inspect the plan

hypit check reference.svml

hypit plan reference.svrun

Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the Scheduler would issue. With a selected Runtime, it also reports only the relevant Endpoint, credential and external-program diagnostics. It never starts external work.

plan may run without a Runtime at all. Both plan and build may omit --runtime after hypit runtime use; build requires either that selection or an explicit Profile.

Use runtime up after selecting or changing a Profile to install selected upstream packages, prepare local Managed Programs and start the local Worker. It does not start or probe remote Endpoints. Use doctor for an active, read-only check of configured remote capabilities. build repeats only the cheap read-only preflight and refuses before submission when a required package or Program is missing; it never provisions dependencies. When the deployment is already prepared and only its Worker is stopped, build starts that Worker before durable submission. runtime status observes the deployment, while programs up|status|down is the narrower lifecycle view for long-lived processes declared by Endpoints.

Permalink to 4-submit-the-build4. Submit the Build

hypit build reference.svrun --title first-cut --follow

Without --follow, build returns after durable submission. The detached Worker continues. With --follow, the terminal is only an observer; it reports durable phase/Operation-count changes and interrupting it leaves the Build running.

Attach or reattach an observer at any time:

hypit status <build-id> --watch

A plain status <build-id> prints one snapshot. status --watch exits when the Result has an outcome; use --max-wait-ms when a script needs a bounded wait.

Each invocation creates a fresh Build id, even when the Author and Run Sources are unchanged. That is necessary for non-deterministic generation: cross-Build reuse belongs only to explicit Candidates in a Run Source. While a Build is active, a Worker restart continues its accepted execution facts and the same external task checkpoints; it never turns another invocation into that Build.

Permalink to 5-inspect-and-retrieve-results5. Inspect and retrieve results

hypit inspect <build-id>

inspect reads the project-owned Result directly and shows its Targets plus a bounded list of completed public Outputs. Use --output <name> for one exact Output or --limit <count> to show more:

hypit get <build-id> \
  --output final.video \
  --to output/final.mp4

get exports one exact build + output address to the required --to destination. A Scalar becomes a JSON file. A Resource becomes one file containing its original bytes. A Composite becomes a self-contained directory: value.json holds its Composite value document and the Resource files it references keep their Result-relative paths inside that directory. The destination must not already exist.

A forwarded historical Output is resolved transparently to its declared earlier Result. This does not create a Build, alter a Result or copy anything back into Result storage, and the Runtime Profile is not involved. Use inspect to view an Output; get is only explicit local export.

The finished Build result prints the exact get --output … command for every file Target; there is no need to inspect opaque Record ids just to export final.video.

Permalink to 6-reuse-in-a-new-build6. Reuse in a new Build

Create a new .svrun file that references the completed Build's Outputs (see Reusing results above), then submit it:

hypit build reuse-generated.svrun --follow

Permalink to 7-diagnose-or-stop-the-local-runtime7. Diagnose or stop the local Runtime

hypit runtime logs
hypit runtime down

runtime down stops the Worker from advancing Builds but leaves external programs running. Use programs down only when those programs should also stop. Neither command cancels durable Builds or remote Provider work. Starting the same Profile again continues its active Builds from their already accepted execution facts.