visionBoard-cli

A command-line interface (CLI) tool for interacting with the visionBoard API.

Requirements

• Node.js (Latest LTS version recommended)

Installation

From npm

npm install -g @openpathfinder/visionboard-cli

From source

# Clone the repository
git clone https://github.com/OpenPathfinder/visionBoard-cli.git
cd visionBoard-cli

# Install dependencies
npm install

# Build the project
npm run build

# Create a global symlink (to use the CLI from anywhere)
npm link

Using npx

npx @openpathfinder/visionboard-cli

Usage

Once installed, you can run the CLI using:

visionboard

This will display the help information with available commands.

Commands

General Commands

# Show version information
visionboard version

# Check compatibility and availability with the API
visionboard doctor

Bulk Import Management

# List all available bulk import operations
visionboard bulk-import list

# Run a bulk import operation
visionboard bulk-import run -i <id> [-d <data> | -f <file>]

Options for bulk-import run:

• -i, --id <id>: Bulk import operation ID (required)
• -d, --data <data>: JSON data to pass to the bulk import operation
• -f, --file <file>: File containing JSON data to be parsed

Note: Exactly one of -d or -f must be provided.

Workflow Management

# List all available compliance workflows
visionboard workflow list

# Execute a compliance workflow
visionboard workflow execute -w <workflowName> [-d <data> | -f <file>]

Options for workflow execute:

• -w, --workflow <workflowName>: Workflow name (required)
• -d, --data <data>: JSON data to pass to the workflow
• -f, --file <file>: File containing JSON data to be parsed

Note: Exactly one of -d or -f must be provided if the workflow requires additional data.

Compliance Checklist Management

# List all available compliance checklists
visionboard compliance-checklist list

Compliance Check Management

# List all available compliance checks
visionboard compliance-check list

Project Management

# Add a project with optional GitHub organizations
visionboard project add -n <name> [-g | --github-orgs <githubOrgUrls...>]

Options for project add:

• -n, --name <name>: Project name (required)
• -g, --github-orgs <githubOrgUrls...>: GitHub organization URLs (optional)

Scripting with visionBoard CLI

The visionBoard CLI can be incorporated into automation scripts for more complex workflows. Below is an example of how to chain multiple operations in a shell script.

The sample script (sample.sh) demonstrates how to:

1. Configure the CLI using environment variables
2. Verify connectivity with the API
3. List available resources for reference
4. Set up a new project with GitHub integration
5. Execute various workflows with and without parameters
6. Perform bulk imports using both inline JSON and file-based input

Configuration

The visionBoard CLI supports configuration through environment variables:

Environment Variables

Variable	Description	Default
VISIONBOARD_INSTANCE_URL	URL of the visionBoard API instance	http://localhost:3000

Note: The URL must include a protocol (http:// or https://).

Example usage:

# Set the API URL for a single command
VISIONBOARD_INSTANCE_URL=https://api.visionboard.example.com visionboard

# Or export it for the current session
export VISIONBOARD_INSTANCE_URL=https://api.visionboard.example.com
visionboard

Development

# Install dependencies
npm install

# Run in development mode (without building)
npm run dev

# Build the TypeScript code
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Type check
npm run type:check

Project Structure

├── .github/workflows/  # GitHub Actions workflows
├── dist/               # Compiled JavaScript output
├── src/                # Source code
│   ├── __tests__/      # Test files
│   └── index.ts        # Main entry point
├── jest.config.js      # Jest configuration
├── package.json        # Project configuration
├── tsconfig.json       # TypeScript configuration
└── README.md           # This file

CI Pipeline

The project includes a GitHub Actions workflow for continuous integration that runs on pull requests to the main branch and when commits are pushed to main. The pipeline performs the following checks in optimized order:

• Linting with StandardJS
• Type checking with TypeScript
• Building the project
• Running tests with coverage reporting
• Verifying binary execution

The pipeline runs on multiple platforms and Node.js versions to ensure maximum compatibility:

• Operating Systems: Ubuntu, Windows, and macOS
• Node.js Versions: 20.x, 22.x, 24.x

Test coverage reports are automatically uploaded as artifacts for each platform and Node.js version combination.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Ulises Gascón — see LICENSE