| title | Your first run | |||
|---|---|---|---|---|
| permalink | /tutorials/first-run | |||
| diataxis | tutorial | |||
| mermaid | true | |||
| redirect_from |
|
In this tutorial you write a Jaiph program, run it, and look at the files the run leaves behind. The program is one .jh file with five lines, and the tutorial takes about five minutes.
The program only runs a script, so you don't need an AI agent or an API key. The next tutorial, Your first agent run, adds a step that calls an agent.
You will write a file with one script that prints a greeting. The program runs the script and returns what the script printed.
- A POSIX shell (
sh,bash,zsh) withcurl,minisign, and eithershasumorsha256sumavailable. The installer usesminisignto verify the release signature andshasumorsha256sumto verify the checksum. It fails closed ifminisignis missing. See Install and switch versions if you need to install withoutminisign. - About five minutes.
Node and API keys are not required for this tutorial. jaiph run executes on the host.
Install the standalone binary:
curl -fsSL https://jaiph.org/install | bashThe installer downloads a per-platform binary, verifies its signature and checksum, and writes it to ~/.local/bin/jaiph. See Install and switch versions for other options, such as JAIPH_BIN_DIR and version switching.
Confirm the install:
jaiph --versionIf the command is not found, prepend the install directory to PATH:
export PATH="$HOME/.local/bin:$PATH"Create a fresh directory and write a file named hello.jh:
script greet = 'echo "Hello, ${1:-world}!"'
export def main(who) {
return greet(who)
}
Here is what each line does:
script greetdeclares a managed script. The body in the example is a single-line bash command. It uses shell positional arguments such as$1and$2, not Jaiph${name}interpolation.${1:-world}is bash default expansion, which suppliesworldwhengreet(...)passes no value. For a multi-line body or another interpreter, see the Script RHS section of the grammar reference.export def main(who)is the run entry. Every.jhfile invoked withjaiph runenters atexport def main. Thewhoparameter is bound by position from the CLI arguments after the file path.return greet(who)calls the script withwhoas${1}, captures its stdout as the step value, and returns it as the run's return value.
Before you run the file, you can look at its steps as a chart. jaiph graph ./hello.jh prints the chart below as Mermaid text, and it doesn't run anything. Execution flow explains every shape and arrow.
subgraph g1 ["def main"] n1(["start"]):::term n2[/"in: who"/]:::input n3["script greet(who)"]:::script n4(["end"]):::term end
n1 --> n2 n2 --> n3 n3 -->|"return"| n4
style g1 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420 </script>{% endraw %}
jaiph run ./hello.jh "Adam"The CLI checks the whole file before it runs the first step, so it reports a mistake such as a call to a script that doesn't exist without running anything. Architecture describes what happens between the command and the first step.
You should see this (timings will differ):
Jaiph: Running hello.jh
def main (who="Adam")
▸ script greet (1="Adam")
✓ script greet (0s)
✓ PASS def main (0.2s)
Hello, Adam!
The first line is the run banner. The def main row and the indented ▸ and ✓ rows are the live progress tree. A ▸ marks a step that has started, a ✓ marks a step that has finished, and (0s) is the elapsed time for that step. The root row is static, and only nested steps print ▸ and ✓ lines. The Hello, Adam! line after PASS is the return value of export def main, which jaiph run prints on stdout after a successful run.
Every run writes durable files under .jaiph/runs/<YYYY-MM-DD>/<HH-MM-SS>-<entry>/ in UTC. List the most recent run:
ls -la .jaiph/runs/*/*/The layout you should see:
000001-def__main.outand.errhold the captured stdout and stderr for the entry def.000002-script__greet.outand.errhold the captured stdout and stderr for thegreetscript step.return_value.txtholds the valuedef mainreturned, and it is written only on success.run_summary.jsonlis the durable event timeline, with records such asRUN_START,STEP_START,STEP_END, andRUN_END.heartbeatis a liveness file that holds an epoch-milliseconds timestamp, refreshed about every 10 seconds while the run is active.
Read the captured script output and the return value:
cat .jaiph/runs/*/*/000002-script__greet.out
cat .jaiph/runs/*/*/return_value.txtBoth should match the line printed after PASS. The full artifact layout is documented in the durable artifact layout section of the architecture page. The event types in run_summary.jsonl are documented in the run artifacts section of the CLI reference.
Replace the script body with one that exits non-zero:
script greet = 'echo "Hello, ${1:-world}!" && exit 7'
export def main(who) {
return greet(who)
}
Re-run with the same arguments:
jaiph run ./hello.jh "Adam"The CLI prints a ✗ FAIL line on stderr, then a block with Logs:, Summary:, out:, and err: lines that point to the run directory, followed by an Output of failed step: excerpt. The process exits non-zero. return_value.txt is not written on failure, only on success.
Revert the failing script body so the run passes again, then pick a direction:
- Your first agent run adds a
promptstep that calls an agent backend. - Pass a host key to a script shows how to grant one host secret with
useand--env. - Language reference covers every step type and expression kind, with their allowed positions and capture rules.
- CLI reference covers every
jaiphsubcommand and flag. - Architecture explains how the CLI, parser, validator, transpiler, runtime, and contracts fit together.