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.

Installation as a CLI tool

npm install -g beyondwork
# or
yarn global add beyondwork
# or
pnpm add -g beyondwork

CLI Usage

Assemble a workblock from a directory

beyondwork 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

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