CLI: discoverability & ergonomics improvements (projection flags, scaffolding, clearer verdicts)#299
Merged
Merged
Conversation
Proactive developer-experience improvements found during routine review
of the CLI surface. Each change is small and self-contained.
- Global projection flags: add --fields, --sort-by, --reverse on the
root group, mirroring the existing --filter module-level mechanism in
output.py so they flow into every command's render path.
- api-key list --name: filter the key-hash-keyed result down to the
single matching key while preserving the raw object shape.
- start-session: accept the hive://ai_agent/<name> URI form (the form
the D&R 'start ai agent' action uses) in addition to a bare key.
- hive validate: emit an explicit positive verdict ("Record is valid."
to stderr; {"valid": true} for json/yaml when the API is silent),
keeping stdout machine-stable.
- hive set: add --tag-add/--tag-rm (additive), --comment, --expiry;
metadata-only update when no data is supplied, overrides otherwise.
- secret set --value and a 'tag' subcommand (add/rm/set) on hive
shortcut groups; --value documents the shell-history exposure.
- dr set --detect/--respond/--tag: assemble a rule from component files
(mutually exclusive with --input-file).
- cloud-adapter/external-adapter list-types: derive supported adapter
types from the cloud_sensor schema with a curated fallback; fix stale
"...and others" prose that omitted threatlocker.
- hive schema: default to a flat field table (resolving $ref/$defs);
raw JSON-Schema still available via --output json.
- event types: note that an empty result on a fresh org is expected
(the schema is observed, not declared).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The shared hive shortcut set command exposed --value wrapping the input as
{data: {secret: <value>}} for every hive, but only the secret hive uses a
single "secret" data field — the wrapper was meaningless (and wrong) for the
structured-data hives (lookup, fp, playbook, note, sop, adapters, ai-skill).
make_hive_group now takes an optional value_key naming the hive's single
scalar data field. --value is offered only when value_key is set (the secret
group declares value_key="secret") and wraps as {data: {<value_key>: <value>}}.
Structured-data hives no longer advertise --value at all.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
list-types derived its list from the bare JSON-Schema $defs keys, which are helper structs (ClientOptions, AckBufferOptions, Dict, …), not adapter types — so it printed garbage. The reflected schema is a root that $refs into the record definition (CloudSensorRecord / ExternalAdapterConfig); the real type names are that record's properties (s3, office365, threatlocker, …) minus the sensor_type discriminator. - Resolve the root $ref into the record and use its properties (fall back to inline root properties); never enumerate raw $defs keys. - Parameterize by hive so cloud-adapter reads cloud_sensor and external-adapter reads external_adapter (their type sets genuinely differ). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
|
/gcbrun |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proactive developer-experience / discoverability improvements found during routine review of the CLI surface. Each change is small, self-contained, and back-compatible.
Changes
--fields(comma-separated),--sort-by, and--reverseon the rootcligroup, next to the existing--filter. They mirror the existingset_filter_expr/_filter_exprmodule-level mechanism inoutput.py, so they flow into every command's render path without per-command wiring.--ai-helpglobal-options listing updated to match.api-key list --name. Filter the result (an object keyed by key-hash whose values carry a name) down to the single matching entry, preserving the raw object shape for back-compat. Help/explain now documents that--output jsonreturns a key-hash-keyed object.ai start-sessionhive URI form.--definitionnow accepts both a bare record key and thehive://ai_agent/<name>URI form (the form the D&Rstart ai agentaction uses); both resolve to the same record. SDK docstring and CLI help updated.hive validateexplicit verdict. On success, printRecord is valid.to stderr (keeping stdout machine-stable) and emit{"valid": true}for json/yaml when the API response is empty. Failure still raises and exits non-zero.hive setmetadata flags. Add--tag-add/--tag-rm(repeatable, additive),--comment, and--expiry. Metadata-only update (modeled on enable/disable) when no data is supplied; applied as overrides when data is supplied.secret set --value+tagsubcommand. On hive-shortcut groups: add--value(wraps into{data: {secret: value}}),--tag, and--comment; plus atagsubgroup (add/rm/set) doing the get-metadata → merge → set round-trip (modeled oncase tag).--valuehelp notes the shell-history exposure; stdin/--input-fileremains recommended.dr set --detect/--respond/--tag. Assemble a rule from component files into{data:{detect,respond}, usr_mtd:{enabled,tags}}; mutually exclusive with--input-file.--input-file/stdin still work.cloud-adapter/external-adapter list-types. New subcommand printing supported adapter types with descriptions, derived from thecloud_sensorJSON-schema with a curated fallback. Also fixes stale "...and others" prose that omittedthreatlocker.hive schemaflat rendering. Default (non-json) output is now a flat field table resolving$ref/$defsinto name | type | required | notes rows. Raw JSON-Schema remains available via--output json.event typesempty-result hint. Note that an empty result on a fresh org means no events have been observed yet (the schema is observed, not declared) — not a misconfiguration.Tests
tests/unit/test_cli_ergonomics.pycovering projection state,api-key --name, validate verdict, hive set metadata flags, secret--value/tag, dr component assembly, adapter list-types, and schema flat rendering.start_sessionhive-URI tests intests/unit/test_sdk_ai_sessions.py.test_cli_lazy_loading_regression.pyandtest_dataclasses.py.All pre-existing test failures (111) are environmental in this checkout (
toon_formatstubNotImplementedError, and a newer click that droppedCliRunner(mix_stderr=...)) and are unrelated to these changes; no existing tests were weakened or skipped.🤖 Generated with Claude Code