Skip to content

docs: update avocado-linux documentation for v0.27–v0.29 CLI changes#403

Merged
mobileoverlord merged 8 commits intomainfrom
jschneck/connect
Mar 13, 2026
Merged

docs: update avocado-linux documentation for v0.27–v0.29 CLI changes#403
mobileoverlord merged 8 commits intomainfrom
jschneck/connect

Conversation

@mobileoverlord
Copy link
Contributor

@mobileoverlord mobileoverlord commented Mar 13, 2026

Summary

  • Add comprehensive avocadoctl documentation (commands, configuration, OS bundles, runtime management, Varlink API reference) and remove the deprecated avocado-control.md page
  • Add avocado connect command docs covering auth, resource management (orgs, projects, devices, cohorts, claim tokens), upload, server key, signing key delegation, and trust posture management
  • Add avocado rootfs and avocado initramfs command docs (install, image, clean)
  • Add erofs-lz4 and erofs-zst filesystem types to ext image docs
  • Update CLI overview and configuration docs with connect, rootfs, and initramfs sections
  • Add guide for customizing rootfs and initramfs packages (including requirement to always include base meta-packages)
  • Update guides and extensions reference for latest CLI changes
  • Regenerate all CLI command help text from latest build

Test plan

  • redocly lint passes
  • eslint passes
  • prettier --check passes
  • docusaurus build succeeds with no errors

@mobileoverlord
docs: add avocadoctl documentation and remove deprecated avocado-cont…
20b6835 
…rol page

Add comprehensive documentation for avocadoctl including commands
(ext, runtime, hitl, merge, refresh, serve, status, etc.),
configuration, OS bundles, runtime management, and Varlink API reference.
Remove the deprecated avocado-control.md page that has been superseded.
@mobileoverlord
docs: update guides and extensions reference for latest avocado-cli c…
40c1de3 
…hanges
@mobileoverlord
docs: add rootfs and initramfs command documentation
9595ef9 
Add docs for the new avocado rootfs and initramfs command groups
(install, image, clean) introduced to manage shared sysroots
independently from runtime builds.
@mobileoverlord
docs: add Avocado Connect platform command documentation
4fb2c53 
Add comprehensive docs for the avocado connect command group covering
auth (login/logout/status), init, resource management (orgs, projects,
devices, cohorts, claim-tokens), upload, server-key, signing key
delegation (register/approve/list/retire), and trust posture management
(status/promote-root/rotate-server-key).
@mobileoverlord
docs: update avocado-cli overview, configuration, and ext image docs
db18879 
Add connect, rootfs, and initramfs mentions to the CLI overview.
Document connect, rootfs, and initramfs config sections.
Add erofs-lz4 and erofs-zst filesystem types to ext image docs.
@mobileoverlord
docs: add guide for customizing rootfs and initramfs packages
b090ef6 
Explain how to add packages to rootfs and initramfs sysroots,
including the requirement to always include the base meta-package
(avocado-pkg-rootfs / avocado-pkg-initramfs) when specifying packages.
Covers filesystem format options, version constraints, and lock file behavior.
@mobileoverlord
docs: regenerate avocado-cli command help text from latest CLI build
f7b9037 
Auto-generated updates from build-avocado-cli script reflecting
current CLI help output across all existing command docs.
Copilot AI review requested due to automatic review settings March 13, 2026 23:15
@mobileoverlord mobileoverlord merged commit 6300d4a into main Mar 13, 2026
5 checks passed
@mobileoverlord mobileoverlord deleted the jschneck/connect branch March 13, 2026 23:20
Copilot AI reviewed Mar 13, 2026
View reviewed changes
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates Avocado Linux documentation to reflect CLI changes across v0.27–v0.29, including new/expanded avocadoctl (on-device) and avocado (build/provision) command references, plus new runtime/OS bundle documentation.

Changes:

  • Add new avocadoctl docs for Varlink API, runtime management lifecycle, OS bundle update flow, configuration, and command reference pages; remove deprecated avocado-control.md.
  • Expand avocado CLI docs with Connect, rootfs/initramfs workflows, and regenerate many command help pages to match current CLI output.
  • Update guides/references to reflect new runtime packaging/meta-package model and new rootfs/initramfs customization guidance.

Reviewed changes

Copilot reviewed 112 out of 112 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md Adds Varlink API overview and C examples for connecting/streaming/errors.
src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md Documents org.avocado.Extensions interface, types, methods, errors, and C examples.
src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md Documents org.avocado.Runtimes interface for staging/activating/removing/inspecting runtimes.
src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md Documents HITL Varlink interface for NFS-based extension mounts.
src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md Documents RootAuthority Varlink interface for TUF root metadata introspection.
src/docs/avocado-linux/tools/avocadoctl/varlink-api/category.json Adds sidebar category for Varlink API docs.
src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md Adds runtime manifest format specification and examples.
src/docs/avocado-linux/tools/avocadoctl/runtime-management/runtime-lifecycle.md Adds conceptual overview of runtime lifecycle states and operations.
src/docs/avocado-linux/tools/avocadoctl/runtime-management/activation-process.md Adds detailed activation flow including OS-update vs extension-only paths.
src/docs/avocado-linux/tools/avocadoctl/runtime-management/category.json Adds sidebar category for runtime management docs.
src/docs/avocado-linux/tools/avocadoctl/os-bundles/overview.md Adds OS bundle overview and relationship to runtimes/manifests.
src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md Specifies bundle.json format for OS bundles (strategy, artifacts, verify, etc.).
src/docs/avocado-linux/tools/avocadoctl/os-bundles/update-process.md Documents end-to-end OS bundle update and post-boot verification.
src/docs/avocado-linux/tools/avocadoctl/os-bundles/category.json Adds sidebar category for OS bundles docs.
src/docs/avocado-linux/tools/avocadoctl/overview.md Adds top-level avocadoctl overview (capabilities, architecture, directory layout, flags).
src/docs/avocado-linux/tools/avocadoctl/configuration.md Adds avocadoctl TOML configuration reference and precedence rules.
src/docs/avocado-linux/tools/avocadoctl/commands/merge.md Adds avocadoctl merge command doc (alias for ext merge).
src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md Adds avocadoctl unmerge command doc (alias for ext unmerge).
src/docs/avocado-linux/tools/avocadoctl/commands/refresh.md Adds avocadoctl refresh command doc (alias for ext refresh).
src/docs/avocado-linux/tools/avocadoctl/commands/status.md Adds avocadoctl status command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/enable.md Adds avocadoctl enable command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/disable.md Adds avocadoctl disable command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/serve.md Adds avocadoctl serve daemon command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/root-authority.md Adds avocadoctl root-authority command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/ext/list.md Adds avocadoctl ext list command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/ext/merge.md Adds avocadoctl ext merge command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md Adds avocadoctl ext unmerge command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/ext/refresh.md Adds avocadoctl ext refresh command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/ext/status.md Adds avocadoctl ext status command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md Adds avocadoctl hitl mount command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md Adds avocadoctl hitl unmount command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md Adds avocadoctl runtime add command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/runtime/list.md Adds avocadoctl runtime list command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md Adds avocadoctl runtime inspect command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md Adds avocadoctl runtime activate command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md Adds avocadoctl runtime remove command doc.
src/docs/avocado-linux/tools/avocadoctl/commands/category.json Adds sidebar category for avocadoctl commands.
src/docs/avocado-linux/tools/avocadoctl/commands/ext/category.json Adds sidebar category for avocadoctl ext subcommands.
src/docs/avocado-linux/tools/avocadoctl/commands/hitl/category.json Adds sidebar category for avocadoctl hitl subcommands.
src/docs/avocado-linux/tools/avocadoctl/commands/runtime/category.json Adds sidebar category for avocadoctl runtime subcommands.
src/docs/avocado-linux/tools/avocadoctl/category.json Adds sidebar category entry for avocadoctl section.
src/docs/avocado-linux/tools/avocado-control.md Removes deprecated avocado-control page.
src/docs/avocado-linux/tools/avocado-cli/overview.md Updates avocado CLI overview capabilities to include Connect + sysroots.
src/docs/avocado-linux/tools/avocado-cli/configuration.md Adds Connect/rootfs/initramfs configuration sections.
src/docs/avocado-linux/tools/avocado-cli/commands/build.md Regenerates/realigns help text formatting for avocado build.
src/docs/avocado-linux/tools/avocado-cli/commands/clean.md Regenerates/realigns help text formatting for avocado clean.
src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md Updates avocado deploy positional runtime name and device flag docs.
src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md Regenerates/realigns help text formatting for avocado fetch.
src/docs/avocado-linux/tools/avocado-cli/commands/init.md Regenerates/realigns help text formatting for avocado init.
src/docs/avocado-linux/tools/avocado-cli/commands/install.md Updates avocado install help text formatting and option descriptions.
src/docs/avocado-linux/tools/avocado-cli/commands/prune.md Regenerates/realigns help text formatting for avocado prune.
src/docs/avocado-linux/tools/avocado-cli/commands/provision.md Updates avocado provision to use positional runtime name.
src/docs/avocado-linux/tools/avocado-cli/commands/sign.md Updates avocado sign to use positional runtime name.
src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md Regenerates/realigns help text formatting for avocado uninstall.
src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md Regenerates/realigns help text formatting for avocado unlock.
src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md Regenerates/realigns help text formatting for avocado upgrade.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md Removes deprecated --extension alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md Updates help text ordering and removes --extension alias.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md Removes deprecated --extension alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md Removes deprecated --extension alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md Regenerates/realigns help text formatting for avocado ext dnf.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md Removes deprecated --extension alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md Updates help text for avocado ext image (now described as squashfs).
src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md Removes deprecated --extension alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md Regenerates/realigns help text formatting for avocado ext list.
src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md Removes deprecated --extension alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md Regenerates/realigns help text formatting for HITL server command.
src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md Adds help text for avocado initramfs install.
src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md Adds help text for avocado initramfs image.
src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md Adds help text for avocado initramfs clean.
src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/category.json Adds sidebar category for initramfs commands.
src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md Adds help text for avocado rootfs install.
src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md Adds help text for avocado rootfs image.
src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md Adds help text for avocado rootfs clean.
src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/category.json Adds sidebar category for rootfs commands.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md Removes deprecated --runtime alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md Removes deprecated --runtime alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md Updates positional NAME ordering and clarifies --device format.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md Removes deprecated --runtime alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md Regenerates/realigns help text formatting for avocado runtime dnf.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md Removes deprecated --runtime alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md Regenerates/realigns help text formatting for avocado runtime list.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md Removes deprecated --runtime alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md Removes deprecated --runtime alias from help text.
src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md Regenerates/realigns help text formatting for avocado sdk clean.
src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md Regenerates/realigns help text formatting for avocado sdk compile.
src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md Regenerates/realigns help text formatting for avocado sdk deps.
src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md Regenerates/realigns help text formatting for avocado sdk dnf.
src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md Regenerates/realigns help text formatting for avocado sdk install.
src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md Updates help text and removes long-form narrative content.
src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md Regenerates/realigns help text formatting for avocado sdk run.
src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md Regenerates/realigns help text formatting for signing key creation.
src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md Regenerates/realigns help text formatting for signing key listing.
src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md Regenerates/realigns help text formatting for signing key removal.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/category.json Adds sidebar category for Connect command group.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md Adds help text for avocado connect init.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md Adds help text for retrieving Connect server key.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md Adds help text for uploading runtime builds to Connect.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/category.json Adds sidebar category for Connect auth commands.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md Adds help text for Connect login.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md Adds help text for Connect logout.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md Adds help text for Connect auth status.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/category.json Adds sidebar category for org commands.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md Adds help text for listing organizations.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/category.json Adds sidebar category for project commands.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md Adds help text for listing projects.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md Adds help text for creating projects.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md Adds help text for deleting projects.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/category.json Adds sidebar category for device commands.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md Adds help text for listing devices.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md Adds help text for creating devices.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md Adds help text for deleting devices.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/category.json Adds sidebar category for cohort commands.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md Adds help text for listing cohorts.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md Adds help text for creating cohorts.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md Adds help text for deleting cohorts.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/category.json Adds sidebar category for claim-token commands.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md Adds help text for listing claim tokens.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md Adds help text for creating claim tokens.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md Adds help text for deleting claim tokens.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/category.json Adds sidebar category for delegate key commands.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md Adds help text for listing delegate keys.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md Adds help text for registering local keys with server.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md Adds help text for approving staged delegate keys.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md Adds help text for discarding staged delegate keys.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/category.json Adds sidebar category for trust commands.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md Adds help text for org trust status.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md Adds help text for promoting root trust level.
src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md Adds help text for rotating server signing key.
src/docs/avocado-linux/references/extensions.md Updates runtime packaging references and adds rootfs/initramfs section.
src/docs/avocado-linux/guides/hardware-in-the-loop.md Updates runtime packages example to use avocado-runtime.
src/docs/avocado-linux/guides/sideloading.md Updates installed package output example to avocado-runtime.
src/docs/avocado-linux/guides/customizing-rootfs-initramfs.md Adds new guide for customizing rootfs/initramfs sysroots and formats.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md
Comment on lines 1 to 3
```
Create a squashfs or erofs image from a system extension
Create squashfs image from system extension

src/docs/avocado-linux/references/extensions.md
Comment on lines +784 to +790
filesystem: erofs.lz4 # default
packages:
avocado-pkg-rootfs: '*'
my-custom-base-package: '*'

initramfs:
filesystem: cpio.zst # default
src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md
Comment on lines +66 to +68
| `manifest_version` | integer | Yes | Schema version. `1` for extensions-only manifests, `2` adds `initramfs_build_id` support. |
| `id` | string | Yes | Unique identifier for this runtime, typically a UUID. Used as the directory name under `runtimes/`. |
| `built_at` | string | Yes | ISO-8601 timestamp of when the runtime was built. |
src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md
Comment on lines +85 to +89
```c
#include <varlink.h>
#include <stdio.h>
#include <stdlib.h>

src/docs/avocado-linux/tools/avocadoctl/runtime-management/runtime-lifecycle.md
Comment on lines +23 to +24
1. Load the local TUF trust anchor (`metadata/root.json`).
2. Download and verify the TUF metadata chain: `timestamp.json` -> `snapshot.json` -> `targets.json`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mobileoverlord