vertex-plm-cli

Vertex PLM CLI Utilities

A cross-platform CLI for interacting with Vertex PLM services and workflows. Built with Node.js + TypeScript using the oclif framework.

Commands available:

• configure — manage credentials and service hosts via a local config file
• set-overwrite — set overwrite policy for a part revision and all related parts
• view-part — look up a registered part revision
• view-part-jobs — view PLM kernel jobs for a part revision
• view-part-structure — view the instance tree (BOM) for a part revision

Requirements

• Node.js >= 16.0.0
• Yarn

Quick Start (Dev)

Install dependencies:

yarn

Build (compile TypeScript to lib/):

yarn build

Run the CLI:

./bin/run --help

Or link it globally so it's available as vertex-plm:

yarn link
vertex-plm --help

Configuration

This CLI requires the following environment variables (or stored config values):

| Variable | Purpose | |---|---| | VERTEX_CLIENT_ID | Vertex Platform OAuth2 client ID | | VERTEX_CLIENT_SECRET | Vertex Platform OAuth2 client secret | | VERTEX_API_HOST | Vertex Platform API base URL (e.g. https://api.vertexvis.com) | | VERTEX_PLM_HOST | Vertex PLM Integration Service base URL | | VERTEX_PLM_API_KEY | Vertex PLM Integration Service API key |

How config works

On startup, the CLI loads:

1. Environment variables already in your shell / CI (highest priority)
2. Config file at ~/.vertex-plm/config.json (fallback)

Config file values only populate process.env.* if the env var is not already set. This means you can safely override stored config in CI:

VERTEX_PLM_API_KEY="ci-key" vertex-plm view-part-structure P123 A

Configure (interactive)

Prompts for each value; leave blank to keep the current stored value:

vertex-plm configure --interactive

Configure (flags)

Set any subset of values directly:

vertex-plm configure \
  --VERTEX_API_HOST https://api.vertexvis.com \
  --VERTEX_PLM_HOST https://plm.example.com \
  --VERTEX_CLIENT_ID "abc" \
  --VERTEX_CLIENT_SECRET "super-secret" \
  --VERTEX_PLM_API_KEY "plm-key"

Show config

vertex-plm configure --show

Secrets are redacted in output:

{
  "VERTEX_CLIENT_ID": "abc",
  "VERTEX_CLIENT_SECRET": "********",
  "VERTEX_API_HOST": "https://api.vertexvis.com",
  "VERTEX_PLM_HOST": "https://plm.example.com",
  "VERTEX_PLM_API_KEY": "********"
}

Unset keys

vertex-plm configure --unset VERTEX_PLM_API_KEY VERTEX_CLIENT_SECRET

Reset config

Deletes the config file entirely:

vertex-plm configure --reset

Config file location

~/.vertex-plm/config.json

Commands

set-overwrite

Sets the overwrite policy in the PLM Integration Service for the given part revision and all related part revisions found in the Vertex Platform instance tree.

Usage

vertex-plm set-overwrite <plm-part-id> <plm-revision-id> [plm-iteration-id]

Examples

vertex-plm set-overwrite P123 A
vertex-plm set-overwrite P123 A 7

view-part

Looks up a registered part revision in the PLM Integration Service and its corresponding entry in the Vertex Platform. If not found in the PLM service, falls back to searching the Vertex Platform directly.

Usage

vertex-plm view-part <plm-part-id> <plm-revision-id> [plm-iteration-id]

Examples

vertex-plm view-part P123 A
vertex-plm view-part P123 A 7

view-part-jobs

Displays PLM kernel jobs associated with a registered part revision.

Usage

vertex-plm view-part-jobs <plm-part-id> <plm-revision-id> [plm-iteration-id]

Examples

vertex-plm view-part-jobs P123 A
vertex-plm view-part-jobs P123 A 7

view-part-structure

Fetches and displays the full part revision instance tree (BOM hierarchy) from the Vertex Platform for the given PLM part revision.

Usage

vertex-plm view-part-structure <plm-part-id> <plm-revision-id> [plm-iteration-id]

Examples

vertex-plm view-part-structure P123 A
vertex-plm view-part-structure P123 A 7

Development

Project structure

src/
  index.ts                       # oclif entrypoint (re-exports run)
  commands/
    configure.ts                 # config file management
    set-overwrite.ts             # set-overwrite command
    view-part.ts                 # view-part command
    view-part-jobs.ts            # view-part-jobs command
    view-part-structure.ts       # view-part-structure command
  lib/
    args.ts                      # shared arg parsing/types
    base.ts                      # BaseCommand (loads config on init)
    config.ts                    # config file load/save/env injection
    prompt.ts                    # interactive prompts (secrets masked)
    plm-api/                     # PLM Integration Service client
    vertex-api/                  # Vertex Platform API client
    tree/                        # generic tree structure for BOM traversal

Running tests

yarn test

Lint and format

yarn lint
yarn format

Pre-commit checks

yarn pre-commit

This runs lint and format together.

Contributing

1. Clone and install:

git clone <repo-url>
cd vertex-plm-cli
yarn

2. Make changes in src/. Keep BaseCommand as the base for all commands — it handles config loading automatically.

3. Build and verify:

yarn build
./bin/run --help
./bin/run --version

4. A good PR should include:
   • A clear description of what changed and why
   • Example command usage
   • Updates to this README if behavior changes

Release Process

This project uses semantic versioning: MAJOR.MINOR.PATCH.

1) Bump the version

npm version patch   # or minor / major

This updates package.json and runs git add package.json (via the version script).

2) Build and verify

yarn build
./bin/run --version
./bin/run --help

3) Commit and tag

If not auto-committed by npm version:

git commit -m "chore(release): vX.Y.Z"
git tag vX.Y.Z

4) Push

git push origin main
git push origin vX.Y.Z

5) Create a GitHub Release

1. Go to Releases → Draft a new release
2. Select the tag vX.Y.Z
3. Add release notes summarizing changes

Troubleshooting

vertex-plm: command not found

If developing locally without linking:

./bin/run --help

Or link globally:

yarn link
vertex-plm --help

Config isn't being applied

vertex-plm configure --show

Remember: environment variables override config file values at runtime.

Host validation errors

VERTEX_API_HOST and VERTEX_PLM_HOST must be valid URLs:

✅ Valid:

• https://api.vertexvis.com
• http://localhost:3000

❌ Invalid:

• api.vertexvis.com (missing protocol)
• vertex-plm-host (not a URL)

Security Notes

The config file stores secrets (client secret + API key) as plain JSON in your home directory. Prefer environment variables in CI and shared environments. Treat ~/.vertex-plm/config.json as sensitive.

License

Internal / TBD.