Concepts > Script Runtime Metadata#

When running scripts via the API or CLI, runtime metadata is available via either environment variables or interpolation in an inline script or appended args.

The environment variables allow scripts to introspect metadata about the project, workspace, and script info.

This same metadata can be referenced within in inline script commands and/or appended script args.

Example#

CLI:#

In this command, all workspaces will run the same script found at the project root, and the workspace name and path will be passed to the script as arguments.

bw run "bun <projectPath>/my-script.ts" --inline \
  --inline-name="my-script-name" \
  --args="<workspaceName> <workspacePath>"

The script itself could use metadata from the environment variables to dynamically change its behavior based on the workspace context passed to it:

// Contents of my-script.ts (in project root)

// All metadata is available as environment variables for use within a script
console.log(process.env.BW_PROJECT_PATH);
console.log(process.env.BW_PROJECT_NAME);
console.log(process.env.BW_WORKSPACE_NAME);
console.log(process.env.BW_WORKSPACE_PATH);
console.log(process.env.BW_WORKSPACE_RELATIVE_PATH);
console.log(process.env.BW_SCRIPT_NAME);

API:#

The same as the above CLI example using the TypeScript API:

import { createFileSystemProject } from 'bun-workspaces';

const project = createFileSystemProject();

project.runScriptAcrossWorkspaces({
  workspacePatterns: ["*"],
  script: "bun <projectPath>/my-script.ts",
  args: "<workspaceName> <workspacePath>",
  inline: { scriptName: "my-script-name" },
});

Available Metadata#

Project Path#

The absolute path to the project root.

In inline scripts and args: <projectPath>
Environment variable: BW_PROJECT_PATH

Project Name#

The name of the project (as in its package.json "name" field).

In inline scripts and args: <projectName>
Environment variable: BW_PROJECT_NAME

Workspace Name#

The name of the workspace (as in its package.json "name" field).

In inline scripts and args: <workspaceName>
Environment variable: BW_WORKSPACE_NAME

Workspace Path#

The absolute path to the workspace.

In inline scripts and args: <workspacePath>
Environment variable: BW_WORKSPACE_PATH

Workspace Relative Path#

The relative path to the workspace from the project root.

In inline scripts and args: <workspaceRelativePath>
Environment variable: BW_WORKSPACE_RELATIVE_PATH

Script Name#

The name of the script. This is an empty string when running as an inline script, unless a script name is explicitly provided.

In inline scripts and args: <scriptName>
Environment variable: BW_SCRIPT_NAME