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 work block from an existing workspace to local filesystem
• Set a work block on a workspace from local files
• Live sync work blocks between open workspaces and local filesystem

Work blocks are expected to be placed in a directory that contains nothing but work blocks. 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 work block

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

Setting a work block

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

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

Syncing work blocks

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