Beyond Work

This extension and cli is for interacting with the Beyond Work platform. This package provides both a VS Code extension and a command-line interface (CLI) for working with Beyond Work workblocks.

VS Code Extension

The Beyond Work VS Code extension enables developers to write, test, and manage Workblocks directly within Visual Studio Code. Using a remote file system, it provides direct access to your Beyond Work Workblocks, making it the ideal tool for developers who want a full-featured editor for creating and updating Workblocks.

Usage

Use this to edit workblocks via VSCode. The extension allows you to connect to Beyond Work and bind workblocks to directories on your local machine. The workblocks in those workspaces can then be stored as files on your local machine.

The extension has 3 features:

• Get a workblock from an existing workspace to local filesystem
• Set a workblock on a workspace from local files
• Live sync workblocks between open workspaces and local filesystem

Workblocks are expected to be placed in a directory that contains nothing but workblocks. When starting from scratch simply create a new directory somewhere.

Getting started

First step is to create a new connection. Click the + button in the BEYOND WORK sidebar, or use CMD-SHIFT-P and type Beyond Work: Add Connection. Then, enter the hostname of the Beyond Work instance you want to connect to. This is the same hostname you use to access the web UI.

Then, click on the connection in the BEYOND WORK sidebar. This will prompt for an API key. You can get this by creating a new token under the account settings.

The connection should now have a blue checkmark. Under it, workspaces with an open editor will be shown. Each of them can be bound to a directory by clicking on them and choosing Choose a directory.

Getting a workblock

Click a workspace in the menu and choose `Get workblock from workspace`. This takes the workblock that's in the workspace provided and downloads it to the directory associated with the workspace.

Setting a workblock

Click a workspace in the menu and choose `Store workblock to workspace`. This takes the workblock files in the associated directory and combines them into a workblock definition and sets it in the workspace provided.

Note that this does not actually store the workblock outside the workspace. In order to do that open the workblock editor in the workspace and click store.

Syncing workblocks

Click a workspace in the menu and choose `Enable sync`.

If a workblock is changed in the UI, either via the editor or by an agent, that change will be reflected in the local files. If local files are changed they are automatically set on the workspace. It's possible to have the UI editor open while editing files locally, the editor will update live as files are saved.

Notice that workblocks are validated before they are set on a workspace. If a workblock is not valid, errors will be shown in the files.

Directory structure

The workblock directory structure is like this:

Base dir/
  work_block_1/
    task_1/
      assets/
        asset1.txt
      task_1.py
    manifest.yaml

CLI Tool

In addition to the VS Code extension, this package provides a command-line interface (CLI) for working with Beyond Work workblocks. In the monorepo it is bin/wb-cli; elsewhere install it as @beyondwork/wb-cli.

Its main use is letting a coding agent (Claude Code, Codex) author a tenant's workblock as local files. To set this up from npm, follow Tools > Claude Code and Codex in your tenant's docs: select Docs in the app, or open https://<tenant>/docs. In the monorepo, see wb-cli/README.md for the three commands a user needs, and the bw-workblock skill in wb-cli/skills/bw-workblock/SKILL.md for what the agent does.

Platform API

wb-cli api exposes every registered platform WebSocket operation. Help and schemas are generated from the same Go handler definitions as the platform clients: each request entry of the generated API schema carries its description, topic, surface and examples. clone, push, run and the other commands remain workflows that also manage local checkout state.

wb-cli api                                      # Studio topics
wb-cli api --list --group permissions
wb-cli api --all --search schedule
wb-cli api permissions_grant --help
wb-cli api permissions_grant --describe          # complete JSON schemas
wb-cli api <operation> '<json>' --tenant <host>
cat request.json | wb-cli api <operation> - --tenant <host>

Discovery defaults to Studio. --surface spaces, --surface admin, and --all expose other areas; all operations remain callable regardless of the discovery view. Calls use your existing sign-in or API token, and the server enforces permissions and caller restrictions. HTTP authentication, blob transfers and browser redirects remain separate from the WebSocket API.

Help comes from the API schema that this wb-cli was built with. The server validates each request. An operation that this wb-cli does not know is still sent; before it sends one, wb-cli reads that operation's warning from the tenant's help. If that help is unavailable or does not list the operation, wb-cli requires --yes after a person confirms its effects.

Some operations deploy to main, publish, merge, delete data, change access, or terminate a workflow. Their --help starts with a warning. Without --yes, the CLI does not send such an operation: it prints the warning as JSON on stderr and exits with code 3. Pass --yes only after a person confirms the warning.

Inside a checkout, calls inherit its tenant and its stream when the operation uses one. Override them with --tenant, --stream, or --no-stream. Raw calls do not update checkout files or the marker. Calls print JSON to stdout; errors preserve the server code in a JSON object on stderr. --timeout sets the request deadline in seconds.

Assemble a workblock from a directory

wb-cli assemble /path/to/workblock/dir [--output output.json]

This command takes a directory containing workblock files and assembles them into a complete workblock JSON object. The structure follows the Beyond Work format:

Base dir/
  work_block_1/
    task_1/
      assets/
        asset1.txt
      task_1.py
    manifest.yaml

import, export, submit, publish-changed-workblocks and list-changed-workblocks remain for CI pipelines and one-off transfers; see wb-cli --help.

Programmatic Usage

You can also use the library programmatically:

import { assembleWorkblock, storeWorkblockFiles } from "beyondwork/lib/utils";

// Assemble a workblock from files
const workblock = await assembleWorkblock("/path/to/workblock");

// Store a workblock as files
await storeWorkblockFiles("/output/path", workblockObject);