Options & Commands
byk's command line has only four layers: options, aliases, file commands, and the program interface. Apart from the words in Reserved Words, every word is treated as an alias to look up — so you can name aliases whatever you like.
Options
Running byk with no arguments produces exactly the same output as byk -h. The first line is always byk <version> (<commit> <build date>) [<platform>], so you can safely grab the version with byk -v | head -1.
When the executable is a symlink, the installed at line gets a -> target suffix, so you can tell which copy actually runs.
CLI Home is byk's home directory, Alias is where global alias files live, and Workdir is the current directory scanned for local files. Drop *.byk.json files into either directory and they join the lookup space.
--paths also lists the top-level alias files in the global alias directory and the current working directory, one group per source. The @@ / @ key prefix tells global from local. File names are validated, but contents are not parsed: a file with broken JSON still appears here, and so do $private files and broken symlinks. Use --check to find content problems. Empty groups are omitted, including their separator.
The alias list in the help page covers the merged space only: aliases marked $private: true never appear, since they are reachable through @file.key alone. An alias with a $cwd gets its effective directory appended, as in deploy deploy.sh (/Users/me/proj).
Diagnostics --check
Problems found while scanning alias files are no longer printed during normal execution. When there are any, the -h banner becomes:
Use byk --check for a per-file report:
With no problems it prints Scanned N alias files; no problems. and exits 0; otherwise it exits 1. Scanned counts the candidate *.byk.json entries encountered, including invalid file names and broken symlinks. It currently covers file reading, JSON parsing, root type, alias and metadata field types, link files, invalid file names, broken symlinks, $mode, $var, and the $deps declaration (including base, target collisions, and package entries). It only looks at configuration: whether dependencies are installed is runtime state, reported by ..deps status. --check takes no alias argument — anything extra fails with check takes no arguments.
Running Aliases
The merged space consists of the global directory ~/.byk/alias/ (priority 0) and the current directory (priority 1); on name collisions, the project's alias wins.
The exact syntax is pure file routing with no fallback:
- missing file →
Alias file not found: @run(@@runfor the global side) - file exists but cannot be loaded →
Alias file cannot be loaded: @run, with the reason and abyk --checkhint - missing key →
Alias key not found in file @run: build - a path segment starts with
$→Not an alias (reserved $ field): @run.build.$cmd
All of them exit with code 1. A $-prefixed segment is a reserved field or custom metadata and is never executed as an alias.
Every alias file also has a set of reserved file commands: @file..command / @@file..command create, edit, clone, install dependencies for, and inspect the file itself. See File Commands.
The __api__ Program Interface
byk __api__ is a read-only interface for programs and editor plugins: it never executes an alias and never writes to disk, so you can call it as often as you like. It does not appear in -h.
The request list, the meaning of every field and worked examples live in Program Interface — that is the page to read when integrating.
Reserved Words
Every word after byk is treated as an alias, with only these exceptions — none of them can be an alias name:
Everything else is free — even words like version or paths work as aliases, as long as they do not start with -.
Match Order
When you run byk <word> ..., the following order applies — the first match wins:
- The
__api__hidden interface - Options such as
-h/-v/--paths/--check @file.key/@@file.keyexact execution- Aliases in the merged space
File commands are handled right before step 3: an @file..command token with .. never reaches alias lookup. When several options are given at once, -h wins, followed by --check, --paths, and -v.
When nothing matches, byk prints Unrecognized command or alias: <word> along with candidate suggestions and exits with code 1.