docs: document infrahubctl CRUD and schema discovery commands - #10016
docs: document infrahubctl CRUD and schema discovery commands#10016petercrocker wants to merge 6 commits into
Conversation
Add a how-to for the new infrahubctl end-user commands (get, create, update, delete, schema list/show) introduced in infrahub-sdk-python#900. - New spoke docs/docs/objects/manage-from-cli.mdx covering interactive object CRUD, output formats, YAML round-trip, and branch targeting - Link it from the Objects hub and the Schema & Data sidebar - Add a schema-discovery note to schema/create-and-load.mdx The exhaustive per-command reference is generated in the SDK repo; these pages stay workflow-focused and link out to it.
petercrocker
added
the
type/documentation
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 4 files
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Shadow auto-approve: would auto-approve. Docs-only addition of a workflow how-to page and a sidebar link. No code, schema, or behavioral changes; clearly beneficial and bounded.
Re-trigger cubic
There was a problem hiding this comment.
Looks good! I added comments in line with suggestions just so you can batch commit. the object parameter was missing from the infrahubctl commands.
Beyond that, and I know this is just a documentation PR, but right now the get commands don't show what the HFID/UUID of the node is, so it's a little difficult to understand from a get what you should then use to go and update/delete an existing node. Also, it would be nice to list the HFID/UUID at the beginning of the table, csv, yaml, or json output just to make those subsequent operations super easy.
| Omit the identifier to list every object of a kind. Empty columns are hidden by default; pass `--all-columns` to show them: | ||
|
|
||
| ```bash | ||
| infrahubctl get InfraDevice |
There was a problem hiding this comment.
| infrahubctl get InfraDevice | |
| infrahubctl object get InfraDevice |
There was a problem hiding this comment.
I know this is just a documentation PR (and not a PR on the feature, but another thought, the ordering from the get shows non-hfid attributes first and doesn't include UUID. It would be good to start the table (leftmost column) with something that can be used to get a device.
| Provide an identifier — a UUID, a name, or an HFID — to display a single object in detail. For a multi-part HFID, separate the components with `/`: | ||
|
|
||
| ```bash | ||
| infrahubctl get InfraDevice spine01 |
There was a problem hiding this comment.
| infrahubctl get InfraDevice spine01 | |
| infrahubctl object get InfraDevice spine01 |
| Filter the results by attribute value with `attribute__value=<value>`: | ||
|
|
||
| ```bash | ||
| infrahubctl get InfraDevice --filter name__value=spine01 |
There was a problem hiding this comment.
| infrahubctl get InfraDevice --filter name__value=spine01 | |
| infrahubctl object get InfraDevice --filter name__value=spine01 |
| Page through large result sets with `--limit` and `--offset`: | ||
|
|
||
| ```bash | ||
| infrahubctl get InfraDevice --limit 10 --offset 20 |
There was a problem hiding this comment.
| infrahubctl get InfraDevice --limit 10 --offset 20 | |
| infrahubctl object get InfraDevice --limit 10 --offset 20 |
| Set field values inline with repeatable `--set key=value` flags: | ||
|
|
||
| ```bash | ||
| infrahubctl create InfraDevice --set name=spine01 --set status=active |
There was a problem hiding this comment.
| infrahubctl create InfraDevice --set name=spine01 --set status=active | |
| infrahubctl object create InfraDevice --set name=spine01 --set status=active |
| ## Reference | ||
|
|
||
| - [`infrahubctl get`]($(base_url)infrahubctl/infrahubctl-get) | ||
| - [`infrahubctl create`]($(base_url)infrahubctl/infrahubctl-create) |
There was a problem hiding this comment.
| - [`infrahubctl create`]($(base_url)infrahubctl/infrahubctl-create) | |
| - [`infrahubctl object create`]($(base_url)infrahubctl/infrahubctl-create) |
|
|
||
| - [`infrahubctl get`]($(base_url)infrahubctl/infrahubctl-get) | ||
| - [`infrahubctl create`]($(base_url)infrahubctl/infrahubctl-create) | ||
| - [`infrahubctl update`]($(base_url)infrahubctl/infrahubctl-update) |
There was a problem hiding this comment.
| - [`infrahubctl update`]($(base_url)infrahubctl/infrahubctl-update) | |
| - [`infrahubctl object update`]($(base_url)infrahubctl/infrahubctl-update) |
| - [`infrahubctl get`]($(base_url)infrahubctl/infrahubctl-get) | ||
| - [`infrahubctl create`]($(base_url)infrahubctl/infrahubctl-create) | ||
| - [`infrahubctl update`]($(base_url)infrahubctl/infrahubctl-update) | ||
| - [`infrahubctl delete`]($(base_url)infrahubctl/infrahubctl-delete) |
There was a problem hiding this comment.
| - [`infrahubctl delete`]($(base_url)infrahubctl/infrahubctl-delete) | |
| - [`infrahubctl object delete`]($(base_url)infrahubctl/infrahubctl-delete) |
| - [`infrahubctl create`]($(base_url)infrahubctl/infrahubctl-create) | ||
| - [`infrahubctl update`]($(base_url)infrahubctl/infrahubctl-update) | ||
| - [`infrahubctl delete`]($(base_url)infrahubctl/infrahubctl-delete) | ||
| - [`infrahubctl schema`]($(base_url)infrahubctl/infrahubctl-schema) |
There was a problem hiding this comment.
| - [`infrahubctl schema`]($(base_url)infrahubctl/infrahubctl-schema) | |
| - [`infrahubctl object schema`]($(base_url)infrahubctl/infrahubctl-schema) |
| infrahubctl schema show <kind> [--branch <branch_name>] | ||
| ``` | ||
|
|
||
| `schema show` prints the attributes and relationships of a kind, which is useful when querying or creating objects with [`infrahubctl`](../objects/manage-from-cli). |
There was a problem hiding this comment.
| `schema show` prints the attributes and relationships of a kind, which is useful when querying or creating objects with [`infrahubctl`](../objects/manage-from-cli). | |
| `infrahubctl schema show` prints the attributes and relationships of a kind, which is useful when querying or creating objects with [`infrahubctl`](../objects/manage-from-cli). |
Address review feedback on PR #10016: - Explain how to find an object's identifier (UUID/name/HFID) for use with update and delete, including via --output json/yaml - Document that update only changes the fields provided and does not clear omitted attributes/relationships, and that --file mode targets the objects declared in the file
|
@PhillSimonds thanks for the review. I looked into the SDK source on opsmill/infrahub-sdk-python#900 before applying the app.command(name="get")(get_command)
app.command(name="create")(create_command)
app.command(name="update")(update_command)
app.command(name="delete")(delete_command)They aren't under the I did address your other points (pushed in cfdfd76):
The output-column ordering (identifier first) and a |
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Confidence score: 3/5
- In
docs/docs/objects/manage-from-cli.mdx, the documented list workflow appears to omit UUID/HFID in JSON/CSV/YAML output, so users can’t obtain the identifier required for subsequentupdate/deletesteps, which can block object management end-to-end. Align the docs with actual CLI behavior (or update examples/commands to surfaceid/HFID in list output) so the workflow is executable.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/docs/objects/manage-from-cli.mdx">
<violation number="1" location="docs/docs/objects/manage-from-cli.mdx:48">
P2: Users cannot follow this documented list workflow to obtain the UUID or HFID needed for a later `update` or `delete`: JSON/CSV/YAML list output omits both identifiers, while only detail JSON includes `id` and the formatters do not emit an HFID field. Please either document querying each object by name/HFID for detail output or update the CLI formatter contract so list output includes the identifiers described here; the affected implementation is opsmill/infrahub-sdk-python#900/infrahub_sdk/ctl/formatters/base.py:80-103.</violation>
</file>
Shadow auto-approve: would not auto-approve because issues were found.
Re-trigger cubic
| infrahubctl get InfraDevice spine01 | ||
| ``` | ||
|
|
||
| The identifier you pass to `update` and `delete` is any of these three values. To find it for an object in a list, use its name or HFID directly, or switch to `--output json` or `--output yaml` to see the object's UUID (`id`) and HFID alongside the other fields. |
There was a problem hiding this comment.
P2: Users cannot follow this documented list workflow to obtain the UUID or HFID needed for a later update or delete: JSON/CSV/YAML list output omits both identifiers, while only detail JSON includes id and the formatters do not emit an HFID field. Please either document querying each object by name/HFID for detail output or update the CLI formatter contract so list output includes the identifiers described here; the affected implementation is opsmill/infrahub-sdk-python#900/infrahub_sdk/ctl/formatters/base.py:80-103.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/objects/manage-from-cli.mdx, line 48:
<comment>Users cannot follow this documented list workflow to obtain the UUID or HFID needed for a later `update` or `delete`: JSON/CSV/YAML list output omits both identifiers, while only detail JSON includes `id` and the formatters do not emit an HFID field. Please either document querying each object by name/HFID for detail output or update the CLI formatter contract so list output includes the identifiers described here; the affected implementation is opsmill/infrahub-sdk-python#900/infrahub_sdk/ctl/formatters/base.py:80-103.</comment>
<file context>
@@ -45,6 +45,8 @@ Provide an identifier — a UUID, a name, or an HFID — to display a single obj
infrahubctl get InfraDevice spine01
+The identifier you pass to update and delete is any of these three values. To find it for an object in a list, use its name or HFID directly, or switch to --output json or --output yaml to see the object's UUID (id) and HFID alongside the other fields.
+
Filter the results by attribute value with attribute__value=<value>:
</file context>
</details>
```suggestion
The identifier you pass to `update` and `delete` is any of these three values. To find it for an object in a list, use its name or HFID directly, or query the object by name or HFID to display its UUID (`id`) in the detailed output.
@petercrocker ofc! Thanks for digging in on this! From the version of infrahubctl infrahub is running (v1.22.2) the environment shows the crud operations as sub commands of 
Those four |
get/create/update/delete are leaf commands of the `object` sub-Typer (`infrahub_sdk/ctl/object/__init__.py`), mounted via `add_typer(object_app, name="object")`, so the correct invocation is `infrahubctl object get` etc. — top-level `infrahubctl get` errors. Also point the reference links at the generated `infrahubctl-object` page with per-command anchors; the previous per-verb pages don't exist.
|
You're right, thanks @PhillSimonds — I was reading an earlier revision of #900, before the object commands were moved into the Fixed in b82b394: all CRUD examples now use the |
There was a problem hiding this comment.
0 issues found across 1 file (changes from recent commits).
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Shadow auto-approve: would not auto-approve. Auto-approval blocked by 1 unresolved issue from previous reviews.
Re-trigger cubic
3 participants
Why
The new
infrahubctlCRUD and schema-discovery commands (get,create,update,delete,schema list,schema show) shipped in opsmill/infrahub-sdk-python#900, but the main docs had no narrative for interactive object management from the CLI. The only documented CLI data workflow was bulk YAML loading.Goal: give users a workflow-focused how-to for the new commands, placed where object-management content already lives, linking out to the generated per-command reference.
Non-goals: does not duplicate the per-command option reference, which is auto-generated in the SDK repo and surfaced at
docs.infrahub.app/infrahubctl.What changed
Behavioral / user-facing:
docs/docs/objects/manage-from-cli.mdx) — schema discovery, query with filters/output formats/pagination, create, update, delete, YAML round-trip withinfrahubctl object load, and--branchtargeting.objects/overview.mdx) and the Schema & Data sidebar (docs/sidebars.ts).schema/create-and-load.mdxforschema list/schema show.What stayed the same: docs-only change. No backend/frontend code, no schema, no generated files.
How to review
Start with
docs/docs/objects/manage-from-cli.mdx. Command signatures and options were verified against the command source in infrahub-sdk-python#900, not the PR summary — note--yesexists only ondelete, and--set/--fileare mutually exclusive oncreate/update.How to test
Both pass locally; the build reports no broken links.
Checklist
Summary by cubic
Adds a workflow-focused how‑to for
infrahubctlobject CRUD and schema discovery from the CLI to enable interactive object management. Examples use theobjectsubcommand (e.g.,infrahubctl object get) and link to the generatedinfrahubctl-objectreference; the page is linked from the Objects hub and the Schema & Data sidebar.schema list/show;object getwith filters, output (table/json/csv/yaml), and pagination;object create,object update,object delete; YAML export +object load; and--branchtargeting.--output json|yaml; explains thatupdateonly changes provided fields and that--filemode targets the objects in the file; adds a schema tip to inspect kinds withschema listandschema show.Written for commit b82b394. Summary will update on new commits.