ecko scaffold

ecko scaffold writes a small, running program of a known shape, then tells you the one command that starts it.

ecko scaffold cli my-tool
cd my-tool
ecko main.ecko --help

Nothing here is required. A .ecko file on its own is still a complete program; scaffolding exists for when you would rather start from something that already runs than from an empty file.

It fetches the first time, then works offline

Templates are not built into the binary. They live in ecko-lang/templates, and the first ecko scaffold you run downloads them and caches them. Every run after that is offline.

This is the only command in the toolchain that needs the network on first use. The trade is that templates can be fixed and added without waiting for an ecko release.

If that first run cannot reach the network it says so, and writes nothing:

ecko scaffold needs to fetch its templates the first time it runs, and that
didn't work:
  fetch 'https://codeload.github.com/...' failed: ...

Once fetched they are cached and work offline.

Templates

Run ecko scaffold with nothing after it to see the list.

Template	What you get
`agent`	An AI agent: a `@tool` the model can call, `ai[T]` output, and contracts
`web`	A web app: routes, path parameters, static files, and tests
`sse`	A streaming app: server-sent events over a channel, with a client
`cli`	A command-line tool: options, a parsed spec, and tests
`package`	An importable package: exports, doc comments, example, and tests

A template can need a newer ecko than yours. --list shows those marked rather than hiding them, and scaffolding one tells you which version it wants.

What lands on disk

Every template is a handful of files, and they follow the same split:

app.ecko holds the logic as exported, documented functions. It binds no

port and reads no arguments.

main.ecko is the entry point that starts it.
tests/<name>_test.ecko tests app.ecko directly, so the suite runs offline

and needs no server and no API key.

ecko.json is the manifest, named after the directory you chose.
README.md says how to run it.

That split is why the generated tests work: the logic is callable without starting anything.

Keeping them current

ecko scaffold --update

That refetches and reports what changed:

Updated templates.
  + queue      added
  ~ web        changed

Nothing refreshes on its own. A cache that quietly refetched would make the same command behave differently on different days. Once a cache is 30 days old ecko scaffold mentions it once and carries on.

Options

Flag	Effect
`--list`	Print the templates and exit. A bare `ecko scaffold` does the same.
`--update`	Refetch the templates and replace the cache.
`--name <n>`	Use `n` as the project name instead of the directory's.
`--force`	Overwrite files that are already there.
`--ref <ref>`	Take the templates from a branch or tag other than `main`.

The project name comes from the last part of the path you give (or the current directory's name for .). Anything outside a-z, 0-9, - and _ becomes a -, so my.tool is named my-tool. A name that does not then start with a lowercase letter is refused rather than mangled, and it says so:

'My-Tool' will not work as a project name: it has to start with a lowercase
letter and use only a-z, 0-9, '-' and '_'. Pass --name to choose one.

It refuses rather than clobbers

ecko scaffold works out every file it would write before writing any of them. If one is already there it names it and stops, having written nothing:

these files are already here:
  my-tool/main.ecko
Nothing was written. Pass --force to overwrite them.

A destination that already has other files in it is fine. Only a collision stops the command, which is what makes ecko scaffold package . safe to run inside a checkout you already have.

Using your own templates

ECKO_TEMPLATES_REPO takes an owner/repo, an archive URL, or a directory path. A directory is read straight through, with no network and no cache, which suits a private set on a shared drive or working on a template:

ECKO_TEMPLATES_REPO=~/my-templates ecko scaffold internal-service svc

ECKO_TEMPLATES_DIR moves the cache.

ecko init writes just an ecko.json, for a

directory you already have.

ecko dev reruns a program when it changes.
ecko build compiles one into a single executable.