osp-cli

osp-cli is a Rust CLI and interactive REPL for querying and managing OSP infrastructure data. It combines structured command output, a small pipeline DSL, layered configuration, themes, and a plugin protocol for external commands.

Status

Published package and active development target. The tool is still most heavily exercised in the UiO OSP environment, but the package itself is the canonical single-crate implementation.

Quick start

cargo run -- --help
cargo run -- config show
cargo run -- theme list
cargo run -- plugins list

Start the REPL:

cargo run

Features

CLI commands and an interactive REPL with history, completion, and inline help
Pipeline DSL for filtering, projecting, grouping, sorting, and aggregating row data (| F uid=alice | P uid cn mail | S cn)
Multiple output formats: table, JSON, markdown, mreg, value
Config files with profile and terminal scoping, environment variable overrides, and secrets handling
Plugin system: external commands discovered and invoked via a JSON subprocess protocol
Theming with color and unicode control
Per-invocation output and debug controls shared between CLI and REPL

Installation

From source

cargo build --release
cp target/release/osp ~/.local/bin/

Bundled plugins (if present) go alongside the binary:

~/.local/bin/osp
~/.local/lib/osp/plugins/
  manifest.toml
  osp-uio-ldap
  osp-uio-mreg

Usage

CLI

# Config management
cargo run -- config show
cargo run -- config get ui.color.mode
cargo run -- config set ui.color.mode always
cargo run -- config explain ui.color.mode

# Plugins
cargo run -- plugins list
cargo run -- plugins commands
cargo run -- doctor

REPL

When started without a command, osp drops into an interactive REPL:

$ cargo run
osp> ldap user alice
osp> ldap user alice | P uid cn mail
osp> config show
osp> theme list
osp> exit

The REPL shares the same command grammar as the CLI. It adds history, tab completion, syntax highlighting, and scoped shells.

Pipeline DSL

Pipelines transform command output using |-separated stages:

Verb	Purpose	Example
`P`	Project columns	`P uid cn mail`
`F`	Filter rows	`F uid=alice`
`S`	Sort	`S cn`
`G`	Group	`G department`
`A`	Aggregate	`A count`
`L`	Limit	`L 10`
`V`	Extract values	`V uid`
`K`	Extract keys	`K`
`?`	Quick search	`? alice`

Bare terms without a verb act as quick search. Quoting rules follow shell conventions ("..." for spaces, \| for literal pipes).

See docs/DSL.md for the full reference.

Configuration

Config file: ~/.config/osp/config.toml Secrets file: ~/.config/osp/secrets.toml (owner-only mode is enforced on Unix)

Precedence (highest first)

Stored config resolution uses:

REPL session overrides
Environment variables (OSP__<KEY>)
Secrets file / OSP_SECRET__<KEY> env vars
Config file
Built-in defaults

Invocation flags such as --json, --format, --color, and --plugin-provider apply only to the current command and do not become stored config values.

Profiles

Config supports profile and terminal scoping:

[default]
ui.color.mode = "auto"

[profile.prod]
ui.color.mode = "never"

[profile.prod.terminal.kitty]
ui.unicode.mode = "always"

Select a profile with --profile prod.

See docs/CONFIG.md for details.

Plugins

External commands are discovered from explicit plugin directories, OSP_PLUGIN_PATH, bundled locations, and the user plugin directory by default. PATH discovery is opt-in via extensions.plugins.discovery.path = true. Plugins communicate via a JSON-over-stdin/stdout protocol, declare their commands with --describe, and receive invocations as subprocess calls.

See docs/WRITING_PLUGINS.md for a guide to writing and packaging plugins.

Documentation

User guide index: docs/README.md
Config and profiles: docs/CONFIG.md
REPL usage: docs/REPL.md
Output and invocation flags: docs/FORMATTING.md
Plugins: docs/USING_PLUGINS.md
Writing plugins: docs/WRITING_PLUGINS.md
Troubleshooting: docs/TROUBLESHOOTING.md

Development

Build and test

./scripts/check-rust-fast.sh
cargo test --all-features --locked

Run locally

cargo run                         # Start REPL
cargo run -- ldap user alice      # Single command
cargo run -- --debug ldap user x

Project layout

src/               Canonical single-crate implementation
tests/             Integration, contract, and PTY tests
docs/              User and contributor documentation
workspace/         Legacy compatibility mirror during the transition

Contributing

Internal project. Contributions welcome from UiO OSP team members.

Commit messages follow <type>(<scope>): <subject> convention. See docs/CONTRIBUTING.md for details.

License

GPLv3

osp-cli 1.4.5