The __api__ Program Interface
byk __api__ is the machine-facing side of byk: 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 — it was never meant for people.
Three rules apply to every request:
- stdout carries data only — warnings and errors go to stderr, so
$(byk __api__ …)always yields a clean value - failure exits 1 — unknown request, missing argument, unsupported shell, unknown path name
- no argument slots beyond the table — one extra argument is an error, not something silently ignored
Requests
Keep the last one close: don't memorise request names, ask for them. The top-level version is the CLI version, matching the first line of -v, so integrations need not parse version text.
completion <shell>
Prints the completion registration script for a shell, which in turn calls complete on Tab. An unsupported shell exits 1 and lists the three that work:
This request exists for the install script; day to day you only need one line (see How completion hooks up).
complete [--with-descriptions] <words...>
Hand it the words already typed on the command line and it returns candidates, one per line. With an @ / @@ prefix it returns file keys only; with a group prefix it returns that group's children. An empty word lists merged aliases only — file keys appear once the word starts with @ / @@. With --with-descriptions, built-in options, file-command verbs, and file keys all carry a tab-separated description; a file key describes itself with its alias file path, home directory shown as ~.
Only aliases stop at the first word. An alias is a single dotted token (grp.inner), so once a word is closed by a space everything after it is passed to the target command as-is and byk cannot know what belongs there — complete grp '' (Tab after byk grp ) returns nothing instead of listing inner as a subcommand. When the cursor sits after a space the shell passes one empty word, and that empty word is exactly what separates "still typing the first word" from "first word already finished".
File commands are the exception: their arguments are interpreted by byk itself, so ..help completes command names, ..remove completes existing keys in the file, ..clone / ..link / ..init --link complete source files, and a command completes its own options. The list lives in File Commands - Completion.
Each call is a read-only scan, and scan-time warnings about alias files (an invalid variable name, say) still go to stderr — stdout holds candidates only, which is why the completion script can wrap it in $(...).
resolve <key> [args...]
Resolves an alias without running it: final command, working directory, PATH prefixes and execution mode. The key accepts either form — a name from the merged space (dep), or the exact syntax (@run.build, @@ops.deploy). File commands are not aliases: @file..command is rejected with exit code 1, and so is a path segment that starts with $ (a reserved field or custom metadata).
file.key
run.build is a dotted path, looked up as a group name inside the merged space, and will usually miss. File keys take a prefix: @run.build.
Two fields deserve their own explanation, because a plugin's correctness rests on them:
commandis a template whenmodeisinteractive. The placeholder values have to be asked of a human, and byk cannot answer for one without a terminal, so it returnsdeploy --env {env}untouched withmode: "interactive". The caller either prompts itself or hands the request back to byk in a terminal; executing that string directly skips the confirmation.pathsis the effective value, not the configured one. Entries are absolutised (relative ones against the alias file's directory), directories that do not exist are dropped, and the working directory'snode_modules/.binis included, along with the dependency directory's venv bin /node_modules/.binwhen the file declares$deps.pip/$deps.npm. An entry written in the file but pointing nowhere will not appear.
paths [name]
Called without a name it returns the directories plus the alias file list, for programs that want everything at once:
The list is enumerated by filename only and content is never read: a file with broken JSON, a missing link target, or a broken symlink is still listed, and whether it is usable is check's job; files with invalid names do not appear. Every value only answers "where is it" and never creates anything.
Reading paths
Shell scripts use paths <name>: it prints that value as a bare string — no quotes, no label, a single trailing newline — exactly the shape $() wants. <name> accepts root, alias, or workdir, matching the JSON fields one-to-one.
A wrong name lists the valid ones and exits 1:
paths <name> deliberately does not wrap its answer in JSON: its caller is a shell script, and wrapping would force jq or sed to strip the quotes, while "$(...)" gets a clean value for free. Programs that want structure call paths with no argument. The human-readable version is still byk --paths — labelled and spaced for reading in a terminal; it shares the same path layout and the same filename enumeration with argument-less paths, and differs only in shape.
file <file-key> / --list
file has two forms: give it a file key to resolve an address, or add --list to list every alias file.
A single key
Resolves a file key to an address without reading the file or requiring it to exist:
It accepts the same key forms as file commands: @name (working directory), @@name (global alias directory), @ / @@ (the anonymous .byk.json). path matches an entry in paths.aliasFiles; key, scope, and dir come on top.
- No existence check: it answers "where would this land under byk's rules", the same path
@run..pathprints, plusscopeanddir. - Address only, not content: to learn which file an alias came from and what it finally runs, use
resolve. - Links are not followed: the result is the location of the link file itself, not its target.
- Alias keys are rejected: the dot in
@run.buildmakes it an invalid filename, exiting 1.
--list
With no key and --list, it returns every alias file, ordered like paths.aliasFiles: global first, then local, each sorted by key. Unlike aliasFiles, it keeps both scope identities, so a directory that serves as both scopes yields two entries. Every entry has the same shape as the single-key response.
The list is enumerated by filename only and content is never read: a file with broken JSON, a missing link target, or a broken symlink is still listed, while invalid filenames do not appear. --list cannot be combined with a key, and an unknown option also exits 1.
expand [--no-builtins] <path>
Expands the variables in a JSON file and prints the result. The argument is an ordinary file path (a relative one is resolved against the process working directory), not an @file key. The flag comes before the path.
--no-builtins expands only the file's own $var declarations: ${byk_dir}, ${work_dir}, ${file_dir} and ${deps_dir} are not injected and stay as written unless $var declares a variable with that name.
By default the rules match ..json --expand:
- Expands
${byk_dir},${work_dir},${file_dir}, and a top-level$var;$varmay override a built-in name;${deps_dir}is additionally injected when the target sits inside the global alias directory - Removes the top-level
$varafter expansion - Unknown
${name}, bare$HOME, and\${...}stay as-is;${args}is an alias placeholder and is not expanded - No alias-structure validation: missing
$var, missing$cmd, or even a non-object root are all fine as long as the JSON parses; built-ins expand unless--no-builtinsis given - Does not follow link arrays, apply inheritance, or execute anything
--no-builtins is available only on the __api__ request (not on ..json --expand): the four built-ins are left unset, while $var removal, name checks, and warnings behave exactly as above. A $var entry named after a built-in becomes an ordinary custom variable.
Problems with $var declarations (invalid names, self-references) only warn on stderr and the request still succeeds with a complete JSON document on stdout. Only an unreadable file, a directory, or invalid UTF-8/JSON exits 1 with an empty stdout.
check
The machine form of byk --check: scans the working directory and the global alias directory — the same two places normal execution reads — and returns the problems found there.
Problems do not change the exit code. The request succeeds as long as it ran, so stdout carries a complete payload and the caller reads items — only a usage error (an extra argument) exits 1. This keeps "there are problems" apart from "the request failed", which is also why the __api__ exit-code rule above does not apply to findings.
The scan is not recursive, exactly like execution: it covers the process working directory plus the global alias directory, so an editor plugin runs one request per directory it wants covered.
How completion hooks up
install.sh writes one line to ~/.zshrc (or ~/.bashrc):
This line forwards Tab events to byk __api__ complete, which scans your aliases in real time and returns candidates. Writing the same line by hand works exactly the same.
Versions and compatibility
Requests get added over time — resolve, paths, file, expand and check all arrived after the first release. When integrating:
- read request names from
byk __api__, never hardcode the list - tolerate unknown fields when parsing the JSON; fields only get added
- check
byk -vfirst — a request the installed version lacks fails with exit code 1