For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /cli/api.md.
  • English
  • 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

    RequestOutput
    __api__ completion <shell>Shell registration script (zsh / bash / fish)
    __api__ complete [--with-descriptions] <words...>Completion candidates, one per line; the flag appends a tab-separated description for built-in options, file-command verbs, and file keys (their alias file path)
    __api__ resolve <key> [args...]Resolved alias, JSON
    __api__ pathsCLI directories, working directory, and alias file list, JSON
    __api__ paths <name>A single bare path (root / alias / workdir)
    __api__ file <file-key> / --listAddress of a single alias file, or the full file list, JSON
    __api__ expand [--no-builtins] <path>Expand variables in a JSON file, JSON output
    __api__ checkScan diagnostics, JSON
    __api__ (no args)Interface manifest, JSON

    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.

    byk __api__
    byk __api__
    {
      "version": "0.8.0",
      "requests": [
        {
          "name": "completion",
          "args": "<shell>",
          "description": "print the shell registration script (zsh|bash|fish)"
        },
        {
          "name": "complete",
          "args": "[--with-descriptions] <words...>",
          "description": "print completion candidates; the flag appends a tab-separated description"
        },
        {
          "name": "resolve",
          "args": "<key> [args...]",
          "description": "resolve an alias to its final command without executing"
        },
        {
          "name": "paths",
          "args": "[name]",
          "description": "print CLI paths and alias file locations as JSON; with <name>, print only that path (root|alias|workdir)"
        },
        {
          "name": "file",
          "args": "<file-key> | --list",
          "description": "resolve an alias file key (@name / @@name) to its path, or list every alias file with --list"
        },
        {
          "name": "expand",
          "args": "[--no-builtins] <path>",
          "description": "expand file-level $var in a JSON file without alias validation; --no-builtins leaves byk_dir/work_dir/file_dir/deps_dir unset"
        },
        {
          "name": "check",
          "args": "",
          "description": "print scan diagnostics as JSON; problems do not change the exit code"
        }
      ]
    }

    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:

    Unsupported shell: pwsh
      Supported: zsh, bash, fish

    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 ~.

    $ byk __api__ complete grp.
    grp.inner

    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).

    Not

    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.

    byk __api__ resolve @run.build --env staging
    FieldMeaning
    keyThe key you passed, echoed back
    sourceThe file key that matched, e.g. @run / @@ops
    sourcePathAbsolute path of that alias file; null only in the rare sourceless case
    commandNon-interactive: the final command with placeholders resolved (arguments are already quoted for the shell, so it can go straight to sh -c); interactive: the unresolved template
    cwdWorking directory the alias would run in (absolute)
    pathsDirectories actually prepended to PATH — see below
    modenormal / interactive / silent
    interactiveDerived boolean for mode == "interactive", kept for callers that only know the boolean
    description$description, or null

    Two fields deserve their own explanation, because a plugin's correctness rests on them:

    • command is a template when mode is interactive. The placeholder values have to be asked of a human, and byk cannot answer for one without a terminal, so it returns deploy --env {env} untouched with mode: "interactive". The caller either prompts itself or hands the request back to byk in a terminal; executing that string directly skips the confirmation.
    • paths is 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's node_modules/.bin is included, along with the dependency directory's venv bin / node_modules/.bin when the file declares $deps.pip / $deps.npm. An entry written in the file but pointing nowhere will not appear.
    byk __api__ resolve int
    {
      "key": "int",
      "source": "@i",
      "sourcePath": "/Users/you/proj/i.byk.json",
      "command": "deploy --env {env}",
      "cwd": "/Users/you/proj",
      "paths": ["/Users/you/proj/scripts", "/Users/you/proj/node_modules/.bin"],
      "mode": "interactive",
      "interactive": true,
      "description": null
    }

    paths [name]

    Called without a name it returns the directories plus the alias file list, for programs that want everything at once:

    byk __api__ paths
    {
      "root": "/Users/you/.byk",
      "alias": "/Users/you/.byk/alias",
      "workdir": "/Users/you/proj",
      "aliasFiles": [
        "/Users/you/.byk/alias/ops.byk.json",
        "/Users/you/proj/run.byk.json"
      ]
    }
    FieldMeaning
    rootCLI root directory, the same as ${byk_dir} inside aliases
    aliasGlobal alias directory
    workdirProcess working directory, where local alias files are looked up
    aliasFilesAbsolute paths of alias files in both directories: global first, then local, each sorted by key; a directory used as both scopes is listed once; an empty array when there are none. Use file --list when you need key, scope, or directory

    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.

    INSTALL_DIR="$(byk __api__ paths root)/bin"
    ALIAS_DIR="$(byk __api__ paths alias)"
    WORKDIR="$(byk __api__ paths workdir)"

    A wrong name lists the valid ones and exits 1:

    __api__ paths: unknown name "bin" (expected one of: root, alias, workdir)

    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:

    byk __api__ file @run
    byk __api__ file @run
    {
      "key": "@run",
      "scope": "local",
      "path": "/Users/you/proj/run.byk.json",
      "dir": "/Users/you/proj"
    }

    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..path prints, plus scope and dir.
    • 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.build makes 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.

    byk __api__ file --list
    byk __api__ file --list
    {
      "files": [
        {
          "key": "@@ops",
          "scope": "global",
          "path": "/Users/you/.byk/alias/ops.byk.json",
          "dir": "/Users/you/.byk/alias"
        },
        {
          "key": "@run",
          "scope": "local",
          "path": "/Users/you/proj/run.byk.json",
          "dir": "/Users/you/proj"
        }
      ]
    }

    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.

    ./config.json
    {
      "$var": {
        "TOOLS": "${byk_dir}/tools"
      },
      "deploy": "cd ${file_dir} && ${TOOLS}/deploy.sh"
    }
    byk __api__ expand ./config.json
    byk __api__ expand ./config.json
    {
      "deploy": "cd /Users/you/proj && /Users/you/.byk/tools/deploy.sh"
    }

    By default the rules match ..json --expand:

    • Expands ${byk_dir}, ${work_dir}, ${file_dir}, and a top-level $var; $var may override a built-in name; ${deps_dir} is additionally injected when the target sits inside the global alias directory
    • Removes the top-level $var after 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-builtins is 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.

    byk __api__ check
    byk __api__ check
    {
      "scanned": 2,
      "errors": 1,
      "warnings": 1,
      "items": [
        {
          "level": "error",
          "path": "/Users/you/proj/gone.byk.json",
          "message": "cannot load link target /Users/you/proj/missing.byk.json: cannot read file: No such file or directory (os error 2)"
        },
        {
          "level": "warning",
          "path": "/Users/you/proj/env.byk.json",
          "message": "$mode must be one of normal|interactive|silent, got \"activ\" (treated as normal)"
        }
      ]
    }
    FieldMeaning
    scannedNumber of candidate *.byk.json entries encountered, including invalid file names and broken symlinks
    errors / warningsItem counts, so a caller can badge without walking the list
    items[].levelerror (file or alias unusable) or warning (still usable, but suspicious)
    items[].pathAbsolute path of the file the problem belongs to
    items[].messageSame text the human-readable report prints

    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):

    # byk shell completion
    if command -v byk >/dev/null 2>&1; then source <(byk __api__ completion zsh); fi

    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 -v first — a request the installed version lacks fails with exit code 1