CLI Commands Matrix

Command Line Interface Reference

POSIX-standard commands, automated test verification, native compiler toolchain detection, and deterministic local workspace generation.

trak init

Core Command

Workspace Scaffolding & Materialization

Full Manual Page

Fetches official or community blueprints from the registry and deterministically materializes the full curriculum directory tree and exercises on local disk.

Command Syntax

$trak init [<author>/]<category>/<tool>[@<version>] [--path <dir>]

Parameter Breakdown

[<author>/]optional

Author Namespace

Optional GitHub username for community tracks (e.g. 'alice/db/postgres'). Omit for official tracks.

<category>

Category Pillar

One of the 5 pillars: lang, os, cloud, db, or tool.

<tool>

Blueprint Identifier

Target tool slug (e.g. go, rust, postgres, docker, aws, linux).

[@<version>]optional

Version Pin

Optional tagged release (e.g. @v1.1.0, @v2.0.0). Defaults to latest.

[--path <dir>]optional

Target Path

Custom output directory. Defaults to './learn-<tool>'.

Flags & Options

Flag	Type	Default	Description
-p, --path <string>	string	./learn-<tool>	Destination folder on your local disk where files will be created.
-h, --help	boolean	false	Display command synopsis, available arguments, and usage tips.

Practical Examples

Official Blueprint Initialization

$ trak init lang/go

Generates the official Go curriculum inside ./learn-go in the current folder.

Community Author Track

$ trak init alice/db/postgres

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

Version-Pinned Release

$ trak init alice/db/postgres@v1.1.0

Pulls stable tagged release postgres@v1.1.0.json, preventing breaking changes.

Custom Workspace Path

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

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

Execution Lifecycle (Under the Hood)

URL Resolution — Resolves official (templates/) or community (users/<author>/) raw URL

AST Validation — Checks JSON schema, max 5MB size limit, and node types

Directory Creation — Recursively creates directory tree on host filesystem

Source Materialization — Writes READMEs, build manifests, code, and exercises (UTF-8)

Metadata Stamping — Records immutable trak.json receipt with version & timestamp

Global Flags & Design Guarantees

The following standard flags and behaviors apply uniformly across all Trak subcommands:

-h, --help

Prints contextual synopsis, available flags, and real-world examples for any command.

trak verify

Executes native test suites across 7 languages and automatically syncs progress in trak.json.

Exit Codes

Returns 0 on success and non-zero on test, validation, or network failures.