WorkLouderCTL — Full-Configuration CLI for Codex Micro

Configure Codex Micro and Work Louder Input from one deterministic, agent-ready CLI.

简体中文 · Commands · Configuration parity · Compatibility · Architecture · Releases

WorkLouderCTL replaces the Codex Micro configuration workflows in Codex and Work Louder Input with a typed command-line interface. It covers all four configuration tiers: Codex-native controls, device layouts, Input host actions, and delegated device operations.

Codex and Input remain the runtime providers for HID/BLE transport, firmware, AppSense, Smart Actions, and Codex-aware behavior. WorkLouderCTL adds the repeatable configuration layer: inspect, plan, diff, apply, verify, and roll back.

Note

Configuration parity is implemented for the verified macOS/Codex Micro boundary. Codex 26.727.51351 and Input 0.18.0 have completed real-device apply/readback/exact-restore transactions and bidirectional provider handoff. The official v0.1.0 release provides signed and notarized Apple Silicon and Intel binaries. Install it from the stable Homebrew tap or with the verified binary installer below.

What it covers

Area	Capabilities
Codex configuration	Agent source, six Agent Keys, six Command Keys, tap behavior, voice mode, dial, joystick, global lighting, layout reset, runtime health and recovery
Input device configuration	Profiles, six layers, key matrix, encoder, radial joystick, Actions, Multi Actions, groups, presets, backlight, underglow and layer metadata
Input host configuration	Smart Actions, Smart Action groups, AppSense links/runtime checks, Cheat Sheet, radial-menu inspection and command permission
Input operations	Device/firmware status, permissions, sanitized logs, firmware plans and delegated update/reset/recovery workflows
Transactions	Immutable backups, exact diffs, revision CAS, idempotent retries, readback, postflight checks, automatic reverse rollback and manual restore
Automation	Stable JSON output, JSON Schemas, shell-free agent envelopes and generated Bash/Zsh/Fish completions

The complete row-by-row acceptance record is in the configuration parity matrix.

Install

Homebrew

Homebrew 6 requires explicit trust for non-official taps. Using the fully qualified formula grants trust only to WorkLouderCTL:

brew tap MarlinDiary/tap
brew install MarlinDiary/tap/worklouderctl
worklouderctl version

Verified binary installer

Download the installer for review, then run it. It verifies the release checksum, fixed archive inventory, manifest, Developer ID signature, and binary version before installing to ~/.local:

curl -fsSLO https://raw.githubusercontent.com/MarlinDiary/worklouder-input-cli/main/install.sh
sh install.sh
~/.local/bin/worklouderctl version

Use sh install.sh --help to select a version or prefix. Add $HOME/.local/bin to PATH if it is not already present.

From source

Requirements:

• macOS
• Rust 1.61 or newer
• installed Codex and Work Louder Input applications
• Node.js 22 or newer for the embedded provider runtime's global WebSocket API

git clone https://github.com/MarlinDiary/worklouder-input-cli.git
cd worklouder-input-cli
cargo build --release --locked
./target/release/worklouderctl version

Install the authenticated provider integrations and verify the machine:

./target/release/worklouderctl provider install codex
./target/release/worklouderctl provider install input
./target/release/worklouderctl provider handoff codex
./target/release/worklouderctl doctor --strict

configurationReady: true means both provider bridges advertise every required apply and restore capability for the installed versions.

The deterministic dual-architecture archives, signature checks, notarization workflow, installer, and automatically updated Homebrew formula are live. See the release guide for verification and packaging details.

Core workflows

Inspect provider and device state

worklouderctl provider status
worklouderctl doctor --strict
worklouderctl device status
worklouderctl device files

Switch the device owner

Only one provider owns the Codex Micro session at a time:

worklouderctl provider handoff input
worklouderctl device status
worklouderctl provider handoff codex

Input is launched as a hidden user-scoped provider during handoff. The CLI uses private authenticated sockets and validates the returned provider/action identity before accepting a result.

Back up, edit and apply an Input configuration

worklouderctl provider handoff input
worklouderctl device config snapshot --output before.json

worklouderctl profile create \
  --input before.json --name "Development" --output candidate.json
worklouderctl config diff before.json candidate.json

worklouderctl device config apply \
  --input candidate.json \
  --backup pre-apply.json \
  --expected-revision REVISION \
  --idempotency-key development-profile-v1

Each semantic editor produces a new candidate file. The source snapshot remains unchanged until an explicit transactional apply.

Configure Codex-native controls

worklouderctl codex config snapshot --output codex-before.json

worklouderctl codex voice set \
  --input codex-before.json realtime --output codex-voice.json
worklouderctl codex lighting brightness set \
  --input codex-voice.json 80 --output codex-candidate.json
worklouderctl codex config diff codex-before.json codex-candidate.json

worklouderctl codex config apply \
  --input codex-candidate.json --backup codex-pre-apply.json

The same command family covers Agent Keys, Command Keys, dial gestures, joystick directions, voice behavior, global lighting and whole-layout reset. The Codex layer's reserved KV_OAI_* device assignments remain read-only in Input control set; inspect them with control list/show and configure their behavior through these Codex-native commands.

Run a coordinated four-authority transaction

worklouderctl transaction plan \
  --codex-settings-base codex-before.json \
  --codex-settings-candidate codex-after.json \
  --codex-agent-keys-base agent-before.json \
  --codex-agent-keys-candidate agent-after.json \
  --input-config-base input-before.json \
  --input-config-candidate input-after.json \
  --input-host-settings-base host-before.json \
  --input-host-settings-candidate host-after.json \
  --output plan.json

worklouderctl transaction apply \
  --plan plan.json \
  --backup-dir backups \
  --receipt receipt.json \
  --idempotency-key workspace-layout-v1

The transaction engine preflights every authority, writes in dependency order, checks exact post-state and reverses completed writes after a failed step.

AI and automation

Human scripts and AI agents use the same parser and transaction core. worklouderctl agent accepts a shell-free JSON envelope, validates expected exit statuses and returns bounded stdout/stderr with a typed result.

worklouderctl --json capability list
worklouderctl --json schema list
worklouderctl --json agent validate --input command.json
worklouderctl --json agent execute --input command.json > result.json

There is one mutation path for every client: snapshot, candidate, diff, apply, readback and rollback.

Architecture

flowchart LR
    Client["Human / script / AI agent"] --> CLI["worklouderctl"]
    CLI --> CodexBridge["Authenticated Codex bridge"]
    CLI --> InputBridge["Authenticated Input bridge"]
    CodexBridge --> Codex["Installed Codex runtime"]
    InputBridge --> Input["Installed Input runtime"]
    Codex --> Device["Codex Micro"]
    Input --> Device

Loading

This split keeps upstream transport, firmware and runtime improvements while making configuration deterministic and reviewable. Provider adapters are version/hash gated; a newly detected build starts with inspection and capability discovery before mutations are enabled.

Safety model

Every guarded write follows the same contract:

1. read the current state from every affected authority;
2. publish an immutable private backup;
3. validate references, versions and limits;
4. show an exact diff;
5. reject stale revisions immediately before writing;
6. apply through the provider-owned serialized queue;
7. read back the complete post-state;
8. restore automatically after a failed mutation;
9. emit a receipt and runnable manual restore path.

Unknown fields are preserved, credentials stay outside snapshots, sockets and tokens use private filesystem modes, and diagnostic bundles are sanitized before publication.

Verified compatibility boundary

Component	Verified boundary
Platform	macOS, Apple Silicon and Intel packaging
Device	Work Louder Codex Micro over USB
Codex	26.727.51351 exact-release overlay
Work Louder Input	0.18.0 exact-release overlay; 0.17.3 sanitized schema fixture
Rust	MSRV 1.61; current stable CI
Node.js	>=22 provider runtime; >=18 Companion conformance runtime

Run worklouderctl doctor --strict against the current machine instead of inferring support from an installed application name. See compatibility for the capability-gating policy.

Documentation

• Complete command reference
• Configuration parity matrix
• Configuration model
• Tier model
• Architecture
• Companion Bridge
• Transactions and rollback
• Compatibility policy
• JSON Schemas
• Release and Homebrew guide
• FAQ
• Changelog

Development

cargo fmt --check
cargo test --locked
cargo clippy --all-targets -- -D warnings
cargo +1.61.0 test --locked
(cd companion && npm test)
node --test \
  scripts/live-bridge-cdp.test.mjs \
  scripts/provider-lock.test.mjs \
  scripts/provider-state.test.mjs

Changes that touch provider behavior should include a baseline, exact commands and outputs, tested version boundaries, readback evidence and rollback results. See CONTRIBUTING.md.

Independence

WorkLouderCTL is an independent community project. It is affiliated with neither Work Louder nor OpenAI. Product names identify compatibility targets.

License

MIT