lucore 0.2.2

Distributed CLI/runtime for local workflows, remote execution, and brokered workers.

Lucore

lucore is a distributed CLI/runtime for local commands, project workflows, and remote execution.

Capabilities

• lucore hello: project overview and common commands
• lucore new: create a project
• lucore dev, lucore build, lucore check, lucore start: default project workflows
• lucore tasks and lucore make: task aliases
• lucore check ...: direct checks such as lucore check ports
• lucore do, lucore find, lucore clean, and lucore fix: common operations
• lucore scan, lucore health, and lucore service: operations and runtime commands
• lucore local-ip, lucore wifi, lucore share, lucore where, lucore open, lucore stop: network and utility commands
• lucore monitor, lucore tail, lucore backup, lucore sync, lucore ssh, lucore git, lucore db: more built-in power
• lucore http, lucore json, lucore csv, lucore image, lucore cron, lucore watch: everyday helpers
• lucore process, lucore download, lucore archive, lucore hash, lucore uuid, lucore time, lucore sysinfo: system utility commands
• lucore deploy, lucore plugin, lucore cloud, lucore docker, lucore ai: even more built-in power
• lucore ports, lucore memory, lucore disk, lucore workers, lucore jobs, lucore scripts: direct shortcuts
• lucore broker: the central scheduler
• lucore worker: a machine that executes jobs
• lucore run and lucore exec: run raw commands locally or on the cluster
• lucore submit: queue distributed work without waiting
• lucore task: define and run project tasks from lucore.toml
• lucore dev: run the project dev task
• lucore invoke: run named commands from lucore.toml
• lucore ps, lucore inspect, and lucore logs: inspect jobs
• lucore cluster workers and lucore cluster jobs: inspect cluster state
• lucore config and lucore doctor: inspect local project/runtime state

The transport is newline-delimited JSON over TCP, so workers can run on completely separate machines.

Installation

PyPI:

pip3 install lucore

Local development:

pip3 install -e .

Quick Start

Start the broker:

lucore broker --listen 127.0.0.1:7000

Start a worker:

lucore worker --broker 127.0.0.1:7000 --name worker-a --label queue=build --label os=mac

Submit a remote command:

lucore run --broker 127.0.0.1:7000 --label queue=build --command "uname -a"

Run a local command:

lucore run --local --command "python3 --version"

Create a starter configuration file:

lucore init
cat lucore.toml

Run project tasks:

lucore hello
lucore tasks
lucore make build
lucore task list
lucore dev
lucore task run build --broker 127.0.0.1:7000
lucore task run test --broker 127.0.0.1:7000

Project workflow:

lucore new my-app
cd my-app
lucore status
lucore dev
lucore build
lucore check

Checks:

lucore check ports
lucore check memory
lucore check scripts
lucore check tasks
lucore check all

Examples:

lucore ports
lucore local-ip
lucore wifi
lucore share 3000
lucore where node
lucore stop port 3000
lucore find text "hello"
lucore do start
lucore clean build
lucore fix deps
lucore make app my-app
lucore health
lucore scan ports
lucore service start ip
lucore monitor cpu
lucore http get https://example.com
lucore json pretty package.json
lucore csv columns data.csv
lucore image info photo.png
lucore process port 3000
lucore download https://example.com page.html
lucore archive create app.zip my-app/
lucore archive extract app.zip --to ./out
lucore hash package.json
lucore uuid --count 3
lucore time utc
lucore sysinfo
lucore cron example "*/5 * * * *" "lucore check ports"
lucore watch --seconds 5 lucore check ports
lucore tail /var/log/system.log
lucore backup my-folder/ my-backup/
lucore ssh user@host
lucore git status
lucore db tables app.db
lucore plugin add greet "echo hi"
lucore do greet
lucore ai prompt deploy

Run a named command:

lucore invoke hello --broker 127.0.0.1:7000 there
lucore invoke python-version --local

Inspect recent activity:

lucore ps --broker 127.0.0.1:7000
lucore cluster workers --broker 127.0.0.1:7000
lucore inspect <job-id> --broker 127.0.0.1:7000
lucore logs <job-id> --broker 127.0.0.1:7000

Configuration

Example:

[project]
name = "my-app"

[tasks.dev]
run = "python3 -m http.server 3000 {args}"
mode = "local"

[tasks.build]
run = "echo building app && uname -a"
mode = "distributed"
labels = { queue = "build" }

[tasks.test]
run = "pytest -q {args}"
mode = "distributed"
labels = { queue = "test", os = "linux" }

[commands.hello]
shell = "echo lucore {args}"
labels = { queue = "build" }

{args} is replaced with any extra arguments passed to lucore task run or lucore invoke.

Command Reference

Examples:

lucore local-ip
lucore wifi
lucore share 3000
lucore check ports
lucore check memory
lucore scan text lucore
lucore find file cli
lucore make ip
lucore do greet
lucore service status
lucore process list node
lucore http head https://example.com
lucore json query package.json '.name'
lucore hash "hello" --string
lucore time now

Runtime Behavior

• Jobs queue until a matching worker is available.
• Labels route work to the right class of worker.
• Workers heartbeat every 5 seconds.
• If a worker disappears mid-job, the broker requeues that job.
• Tasks can run locally or distributed depending on config and flags.
• The broker keeps recent job history and stored logs in memory.
• Named commands are real config-driven commands, not fake placeholders.

Production Considerations

Recommended enhancements for production deployment include TLS/authentication, persistent broker state, streaming logs, retry policies, and sandboxed execution.