CLI Commands/init

trak init

Fetches official or community blueprints from trak-registry and recursively materializes the entire workspace directory tree on disk.

$ trak init [<author>/]<category>/<template>[@<version>] [flags]

Command Overview

Supports official templates (e.g. 'trak init lang/go'), explicit namespace ('trak init trak/lang/go'), community author tracks ('trak init <username>/<category>/<tool>'), and pinned version releases ('trak init <username>/<category>/<tool>@<version>'). If --path is omitted, it defaults to './learn-<template>' in the current working directory.

Execution Lifecycle

Resolves blueprint URL (official: templates/<category>/<tool>.json, community: users/<username>/<category>/<tool>[@<version>].json)

Parses recursive JSON AST node hierarchy (directories, files, and build manifests)

Creates target directory and recursively writes all files with UTF-8 encoding

Stamps immutable trak.json manifest containing author attribution, version, and UTC timestamp

Prints success banner with total resource count and recommended next steps

Available Flags

-p, --pathType: string • Default: ./learn-<template>

Target directory path where the workspace will be materialized.

-h, --helpType: boolean • Default: false

Show help message and command examples.

Usage Examples

Official Blueprint Initialization

$trak init lang/go

Generates the official Go workspace in ./learn-go in your current folder.

Community Author Track

$trak init alice/db/postgres

Fetches community track from users/alice/db/postgres.json in the registry.

Version-Pinned Release

$trak init alice/db/postgres@v2.0.0

Pulls tagged release postgres@v2.0.0.json, preserving stability for learners.

Custom Workspace Path

$trak init lang/rust --path ./my-rust-lab

Materializes the Rust workspace inside custom ./my-rust-lab directory.

Important Technical Guidelines

Workspace Context Receipt

The initialization process generates a trak.json manifest at the root of the new folder. This receipt is essential for all tracking commands (trak verify, trak next, trak status, trak done).

Path Clobber Safety

Trak safely writes to target directories and preserves folder structure. Use the --path flag if you want to isolate workspaces in custom locations.

Frequently Asked Questions (FAQ)

Q:Can I initialize in a custom folder?

Yes, use the --path flag: 'trak init lang/go --path ./custom-folder'.

Q:Can I use trak offline?

Initialization requires internet access to fetch blueprints from GitHub Raw. Once materialized, your entire workspace runs 100% locally and offline.