Commands

opctl

Options

-v or --version

To print the version and exit, specify a -v (or --version) flag.

Examples
opctl -v

--data-dir or OPCTL_DATA_DIR default: OS dependent per user app data

To specify the path of the directory used to store opctl data, include a --data-dir or set an OPCTL_DATA_DIR env var. to a relative or absolute path.

Examples

opctl --data-dir . node create
export OPCTL_DATA_DIR=. && opctl node create

--listen-address or OPCTL_LISTEN_ADDRESS default: 127.0.0.1:42224

To specify the HOST:PORT on which the node will listen, include a --listen-address or set an OPCTL_LISTEN_ADDRESS env var.

Examples

opctl --listen-address 0.0.0.0:42224

--nc

To disable color, include a --nc flag w/ your command.

this may increase readability in environments not supporting color escape codes or piping output to another program.

Examples
opctl --no-color events

-h or --help

For context specific help, include a -h (or --help) flag w/ your command.

Examples
opctl node create -h
Usage: opctl node create
Creates a node

opctl events

listen to node events.

if a node isn't running, one will be automatically created.

Examples

Event Replay

Events are persisted to disk and can be replayed.

events are not held across node restarts; any time a node starts it clears its event db.

  1. open terminal & run an op so we have some events

    opctl run github.com/opspec-pkgs/uuid.v4.generate#1.1.0
  2. exit terminal

    exit
  3. re open terminal & replay events

    opctl run events

Event Streaming

Events are streamed in realtime as they occur. They can be streamed in parallel to any number of terminals.

behind the scenes, events are delivered over websockets

  1. open multiple terminals & open event stream on each

    opctl events
  2. open another terminal & run an op; watch events show up on all terminals simultaneously in real-time

    opctl run some-op

opctl ls [DIR_REF]

List ops in a local or remote directory.

Arguments

DIR_REF default: .opspec

Reference to dir ops will be listed from (either relative/path, /absolute/path, host/path/repo#tag, or host/path/repo#tag/path)

Examples

.opspec dir

lists ops from ./.opspec

opctl ls

remote dir

lists ops from github.com/opctl/opctl#0.1.24

opctl ls github.com/opctl/opctl#0.1.24/

opctl run [OPTIONS] OP_REF

Start and wait on an op

if a node isn't running, one will be automatically created

Arguments

OP_REF

Op reference (either relative/path, /absolute/path, host/path/repo#tag, or host/path/repo#tag/path)

Options

-a

Explicitly pass args to op in format -a NAME1=VALUE1 -a NAME2=VALUE2

--arg-file default: .opspec/args.yml

Read in a file of args in yml format

Examples

local op ref w/out args

opctl run myop

remote op ref w/ args

opctl run -a apiToken="my-token" -a channelName="my-channel" -a msg="hello!" github.com/opspec-pkgs/slack.chat.post-message#0.1.1

Notes

op source username/password prompt

If auth w/ the op source fails the cli will (re)prompt for username & password.

in non-interactive terminals, the cli will note that it can't prompt due to being in a non-interactive terminal and exit with a non zero exit code.

input sources

Input sources are checked according to the following precedence:

  • arg provided via -a option
  • arg file
  • env var
  • default
  • prompt

input prompts

Inputs which are invalid or missing will result in the cli prompting for them.

in non-interactive terminals, the cli will provide details about the invalid or missing input, note that it's giving up due to being in a non-interactive terminal and exit with a non zero exit code.

example:

-
Please provide value for parameter.
Name: version
Description: version of app being compiled
-
validation

When inputs don't meet constraints, the cli will (re)prompt for the input until a satisfactory value is obtained.

containers

image
image layer caching

All pulled image layers will be cached

image updates

Prior to container creation, updates to the referenced image will be pulled and applied.

If checking for or applying updated image layers fails, graceful fallback to cached image layers will occur

networking

All containers created by opctl will be attached to a single managed network.

the network is visible from docker network ls as opctl.

cleanup

Containers will be removed as they exit.

opctl node create

Create an in-process node which inherits current stderr/stdout/stdin/PGId (process group id) and blocks until killed.

There can be only one node running at a time on a given machine.

Options

--data-dir

Path of dir used to store node data

Notes

lockfile

Upon creation, nodes populate a lockfile at DATA_DIR/lockfile.pid containing their PId (process id).

concurrency

Prior to node creation, if a lockfile exists, the existing lock holder will be liveness tested.

Only in the event the existing lock holder is dead will creation of a new node occur.

debugging

Debugging can be accomplished by running node create from a terminal where it's output is easily monitored.

cleanup

During creation, DATA_DIR will be cleaned of any existing events, ops, and temp files/dirs to ensure the created node starts from a clean slate.

opctl node kill

Kill the running node.

opctl op create [OPTIONS] NAME

Creates an op

Arguments

NAME

Name of the op

Options

-d or --description

Description of the op

--path default: .opspec

Path to create the op at

Examples

opctl op create -d "my awesome op description" --path some/path my-awesome-op-name

op install [OPTIONS] OP_REF

Installs an op

Arguments

OP_REF

Op reference (host/path/repo#tag, or host/path/repo#tag/path)

Options

--path default: .opspec/OP_REF

Path to install the op at

-u or --username

Username used to auth w/ the op source

-p or --password

Password used to auth w/ the op source

Examples

opctl op install -u someUser -p somePass host/path/repo#tag

Notes

op source username/password prompt

If auth w/ the op source fails the cli will (re)prompt for username & password.

in non-interactive terminals, the cli will note that it can't prompt and exit with a non zero exit code.

op kill OP_ID

Kill an op.

Arguments

OP_ID

Id of the op to kill

op validate OP_REF

Validates an op according to:

  • existence of op.yml
  • validity of op.yml (per schema)

Arguments

OP_REF

Op reference (either relative/path, /absolute/path, host/path/repo#tag, or host/path/repo#tag/path).

Examples

opctl op validate myop

Notes

op source username/password prompt

If auth w/ the op source fails the cli will (re)prompt for username & password.

in non-interactive terminals, the cli will note that it can't prompt and exit with a non zero exit code.

opctl self-update [OPTIONS]

Updates the current version of opctl.

if a node is running, it will be automatically killed

Options

-c or --channel default: stable

The release channel to update from

  • stable
  • beta (smoke tested alpha channel)
  • alpha (all bets are off)

Examples

get latest stable release

opctl self-update
# output: Updated to new version: 0.1.24!

play around w/ latest beta release

opctl self-update -c beta
# output: Updated to new version: 0.1.24-beta.1!

play times over; switch back to latest stable release

opctl self-update
# output: Updated to new version: 0.1.24!

ui [MOUNT_REF]

Opens the opctl web UI and mounts a reference.

Arguments

MOUNT_REF default: .

Reference to mount (either relative/path, /absolute/path, host/path/repo#tag, or host/path/repo#tag/path).

Examples

Open web UI to current working directory

opctl ui

Open web UI to remote op (github.com/opspec-pkgs/_.op.create#3.3.1)

opctl ui github.com/opspec-pkgs/_.op.create#3.3.1
Last updated on by Chris Dostert