Repository navigation
Releases
v0.1.6-rc2
v0.1.6-rc2 (prerelease)
Second prerelease of PUDA CLI 0.1.6. Not marked Latest; install it explicitly:
puda update v0.1.6-rc2
puda skills updateChanges since v0.1.6-rc1
Healthcheck
puda healthcheckprints exactly one JSON report and nothing else.- SDK compatibility is part of that report as a
compatibilityobject aftergateways(advisory only; never changes status or exit code). - Each transport error is reported once, on the affected server. Dependent checks carry
status/reason:not_checkedwhen they could not run,failedwhen they ran and failed. - JetStream and discovery permission errors are captured in the report instead of leaking to stderr.
- An unhealthy report exits 1 with no extra
Error:line or stderr prose. Config and output errors are still shown.
Identity
- Login is optional. Commands that need an identity create a default one: your OS username plus a generated user ID, marked
user.default: true(shown bypuda config list). puda login --username <name>replaces the default identity and keeps its user ID. Simulated authentication messages were removed.puda logoutclears only the user identity; NATS profiles and other settings are kept.- An unreadable or invalid global config is never deleted; commands return an error and leave the file unchanged.
Other CLI fixes
puda init --helpnow says it createspuda.config.
Skills
Skills are versioned with the CLI; run puda skills update after updating.
- Recovery after a failed protocol:
puda machine reset, then rerun the protocol from the failed step with--steps <N>-. puda-manual-uiis framework-agnostic: a UI only needs to drivepuda machine start,runandcomplete, and takes livestream URLs frompuda machine info. Streamlit is an example, not a requirement.puda-deploymentmapspuda healthcheckreport fields to troubleshooting steps.- Fixed outdated guidance and registry keys; removed CLI version gates and the legacy
experiment.mdmarker. - Removed unused
puda-datacode and duplicated command lists; skills point topuda <command> --helpinstead.
Upgrading from 0.1.5
Follow the v0.1.6-rc1 upgrade steps. In short:
- Stop database writers and back up the project database with SQLite's backup API.
puda update v0.1.6-rc2.- From the project root, apply and confirm the additive migration (
run.steps,run.notes):
puda db exec "SELECT name FROM pragma_table_info('run') WHERE name IN ('steps', 'notes')" puda skills update(installs skills from this tag; same-name skills fromPUDAP/skillsare replaced, legacy-only skills are left in place).
From v0.1.6-rc1, only steps 2 and 4 are needed.
Prerelease caveat
This binary reports version 0.1.6-rc2. The compatibility policy only matches stable CLI versions, so SDK compatibility is reported as unknown.
Python SDK
SDK 0.0.22 is a separate PyPI release (see the v0.1.6-rc1 notes); this CLI neither requires nor installs it.
Verification
- Built with GoReleaser from tag
v0.1.6-rc2(commit7d0263d); all binaries report0.1.6-rc2. Root and CLIgo vet/go testpassed (CLI tests with a local NATS server, no skips). Archive checksums verified. - Default
puda skills installinstalled all seven skills from thev0.1.6-rc2tag in an isolated home; files matched the tag. healthcheckagainst an unreachable server: one JSON report, exit 1, empty stderr.config listin a fresh home shows the default identity.- Not tested in this round: hardware, encrypted (TLS) brokers, live edges.
v0.1.6-rc1
v0.1.6-rc1 (prerelease)
Prerelease of PUDA CLI 0.1.6. Not marked Latest; install it explicitly:
puda update v0.1.6-rc1
puda skills updateHighlights
- Skills are versioned with the CLI. The seven PUDA agent skills now live in this repo (
skills/) and are tagged with each CLI release.puda skills install/updateinstall the skills from the installed CLI's release tag, so skills always match the CLI they describe. Runpuda skills updateafter everypuda update. - Run notes.
puda protocol note --run <run-id> --text <summary>appends a timestamped summary (Markdown links to reports, plots and data are kept) to a protocol run.run.stepsrecords the--stepsselection used. - Python SDK compatibility advisories.
machine list,machine info,healthcheckandpuda updatecheck each responding edge's reported SDK version againstcompatibility.json. Advisory only: results and exit codes are unchanged.
Skills
- Installed from
PUDAP/pudaat this release's tag (v0.1.6-rc1) instead of the separatePUDAP/skillsrepository. --ref <branch-or-tag>selects another version, e.g.--ref main. A missing tag fails instead of falling back tomain.- Same-name skills from
PUDAP/skillsare replaced; back up local edits first. Skills that exist only in the old repo (e.g.puda-memory) are left in place. Streamlit skills are no longer installed automatically. - Details:
docs/skills-migration.md.
Compatibility advisories
- Policy:
compatibility.jsonat the repo root, with inclusive ranges: CLI 0.1.0–0.1.6 with SDK 0.0.17–0.0.22; legacy CLI 0.0.0–0.0.36 with SDK 0.0.15–0.0.16 (declared, not tested). - Uses the version each running edge reports, not locally installed packages. Unknown, development or unparseable versions report
unknown; edges that don't respond can't be checked. puda updatechecks the target release's own policy before installing and lists affected machines.- Prerelease caveat: this binary reports version
0.1.6-rc1, and the policy only matches stable CLI versions, so its advisories report SDK compatibility asunknown.
Removed
puda machine ping. Usepuda machine info <machine_ids>.
Upgrading from 0.1.5
The database change is additive: two nullable columns, run.steps and run.notes, are added the first time the CLI opens a project database. Existing rows keep their values; queries using named columns are unaffected (SELECT * returns two more columns).
-
Stop protocol runs and other database writers.
-
Back up the database with SQLite's backup API (not a file copy while it's in use):
import sqlite3 with sqlite3.connect("puda.db") as src, sqlite3.connect("puda.db.before-0.1.6-rc1") as dst: src.backup(dst)
-
Install
v0.1.6-rc1, then from the project root run a query to apply and confirm the migration:puda db exec "SELECT name FROM pragma_table_info('run') WHERE name IN ('steps', 'notes')"
It should return both columns. (
puda db schemaonly prints the bundled schema; it doesn't prove the database was migrated.) -
Run
puda skills update.
Don't run puda init on an existing project to upgrade it. project.md is unchanged; keep project goals and decisions there, and use puda protocol note for per-run summaries. Old runs have NULL steps and notes, which means "not recorded".
Python SDK 0.0.22 (separate release)
Published separately on PyPI (puda==0.0.22). It wraps telemetry health/stream payloads in {timestamp, data}, so consumers must accept the new envelope before edges are upgraded. This CLI release neither requires nor installs it, and doesn't touch running edges.
Verification
- Built with GoReleaser from tag
v0.1.6-rc1(commitead496b); binaries report0.1.6-rc1. Go tests/vet and all archive checksums passed. puda skills installfrom this binary installed all seven skills from thev0.1.6-rc1tag in an isolated home; files matched the tag.- Database migration, concurrent notes and a software-only NATS broker test (SDK 0.0.21) passed on the same commit. Hardware, encrypted connections and telemetry consumers were not tested.
v0.1.5
Changelog
🐛 Bug Fixes
- f82f30f fix(cli): create run before logging lifecycle responses
Released by GoReleaser.
v0.1.4
Fixes
- Fix
puda machine run --run-id <RUN_ID>failing withUNIQUE constraint failed: run.run_idwhen multiple commands share a run ID and project database logging is enabled. - Preserve existing run metadata and command logs when reusing a run ID. Protocol duplicate-ID checks remain unchanged.
Validation
- All CLI Go tests pass, including regression coverage for run ID reuse across database connections and preservation of existing records.
Released by GoReleaser.
v0.1.3
Breaking Changes
puda envis removed. NATS connections are named profiles:puda profile add,list,current,switch,set, andremove.puda configonly manages the logged-in user. Server URLs live on the active profile. Project settings are managed withpuda project config.- A
nats_serversvalue saved in the user config is no longer read. Add it again withpuda profile add.
Changes
- Payload encryption belongs to an encrypted profile (
tls://with--caand--key).puda encryption statusandpuda encryption rotaterequire that profile. - A plaintext profile uses
nats://and leaves encryption off.
Released by GoReleaser.
v0.1.3-rc1
Breaking Changes
puda envis removed. NATS connections are named profiles:puda profile add,list,current,switch,set, andremove.puda configonly manages the logged-in user. Server URLs live on the active profile. Project settings arepuda project config.- A
nats_serversvalue saved in the user config is no longer read. Add it again withpuda profile add.
Changes
- Payload encryption belongs to an encrypted profile (
tls://with--caand--key).puda encryption statusandpuda encryption rotaterequire that profile. - A plaintext profile uses
nats://and leaves encryption off.
Released by GoReleaser.
v0.1.2
Breaking Changes
- Position moved from
puda.<machine_id>.tlm.posto telemetry streams onpuda.<machine_id>.tlm.stream.<name>. Update dashboards and loggers subscribed totlm.pos. puda machine watchtakes full NATS subjects as arguments, e.g.puda machine watch 'puda.<machine_id>.tlm.stream.>'.--subjects/-sand--targetsare removed;--machines/-mstays.puda machine pingis renamed topuda machine info(pingremains an alias).
Changes
puda machine infolists each machine's telemetry streams (tlm_streams) with subject, interval, and description.puda machine listshowstlm_stream_count.puda machine watchsubscribes server-side, so it only receives the subjects you ask for. Heartbeats are hidden unless--include-heartbeatis set or a subject namestlm.heartbeat.
Python SDK 0.0.18
@tlm_stream(interval=..., name=...)publishes live readings at their own rate, in a worker thread.@machine_stateadds driver fields to everyMACHINE_STATEupdate.EdgeRunnerpublishes the heartbeat and host health (CPU, memory, temperature) on its own;main.pyonly needsEdgeRunner(nats_client=..., machine_driver=...).
Upgrade guide: https://docs.puda.co/docs/upgrading-to-0.1.x
Full Changelog: v0.1.1...v0.1.2
Released by GoReleaser.
v0.1.1
Changes
- Machine ping includes host addresses. Edges publish
local_ip,tailscale_ip, andmagicdns, andpuda machine list/puda machine pingshow them. puda updatehides release candidates unless the version you ask for is itself a pre-release.
Full Changelog: v0.1.0...v0.1.1
Released by GoReleaser.
v0.1.0
Breaking Changes
- Edge driver methods must be marked
@commandor they are not advertised or callable. Update the Python SDK to 0.0.17 (puda>=0.0.17). - Machine KV is no longer one bucket per machine. Shared
MACHINE_STATEandMACHINE_COMMANDSbuckets usemachine_idas the key. MACHINE_COMMANDSnow requires a structuredcatalog(name, signature, doc, safety). A v0.0.36 edge that only published command text will failpuda machine commandsand protocol validate.- CLI machine output is JSON by default. Use
--humanfor text (list,ping,state,commands).
Changes
- Core NATS ping/pong (
puda.<id>.cmd.pingand broadcastpuda.cmd.ping) withsdk_version,uptime_seconds,run_status, and optionaldescription. puda machine listdiscovers live edges from pong replies and reportsmachine_id,description, and registered-onlylivestream_count.puda machine pingprobes specific IDs.puda machine commandslists the live command catalog.@safetyon driver commands; protocol run/validate uses the live catalog for confirmation.--yesskips confirmation.waitis a special client-side protocol command (params.seconds); the CLI sleeps locally and does not send it to a machine.puda livestreamfleet registry (add,list,attach,detach,rm); HLS/RTSP/RTMP/WebRTC URLs derived from host and stream name.puda healthcheckprobes each NATS URL, cluster membership, JetStream, and optional--gateway-servers.- Chrony NTP server (
infra/chrony) and edge client scripts (infra/chrony/client). - JetStream streams declared as JSON config;
NATS_PORTandEXTERNAL_PORT; single-node and three-node (R3) NATS layouts. - Telemetry throttled: heartbeat at most every 5s, position at most every 3s.
- Immediate-command default timeout is 10s (was 120s). Missing driver
resetis a successful no-op that clearsrun_id. puda config set user.user_id/user.usernameafter login;puda config editopens a terminal editor.puda updatecan install pre-release versions.- Protocol validate parses JSON primitive annotations (nested dict/list, typing aliases, unions, Any). Only commands named in the protocol are parsed; unused catalog signatures are ignored. Unannotated parameters,
*args, and**kwargsskip the type check. puda-loadgenandtest-edgefor fleet-scale testing.- Python SDK:
CommandProcessorextracted fromEdgeNatsClient. - CLI build/release docs;
just publishaccepts piped release notes.
Full Changelog: v0.0.36...v0.1.0
v0.1.0-rc4
Changes
- Parse JSON primitive annotations in protocol validate so nested dict/list, typing aliases, unions, and Any catalogs no longer fail
- Expand test-edge to cover those primitives and safety confirm variants
Released by GoReleaser.