@safetech/inheriti-cli 0.0.21-dev.0 → 0.0.22-dev.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@safetech/inheriti-cli",
3
- "version": "0.0.21-dev.0",
3
+ "version": "0.0.22-dev.0",
4
4
  "description": "Inheriti CLI (TEST builds only).",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: inheriti-cli
3
- description: Use the Inheriti CLI to find, create, inspect, reveal, download, or use protected plans and to configure Business automations from a user's natural-language request.
3
+ description: Use the Inheriti® CLI to find, create, inspect, reveal, download, or use protected plans and to configure Business automations from a user's natural-language request.
4
4
  metadata:
5
- version: 0.0.21-dev.0
5
+ version: 0.0.22-dev.0
6
6
  ---
7
7
 
8
- # Inheriti CLI
8
+ # Inheriti® CLI
9
9
 
10
10
  Turn the user's requested outcome into the smallest supported CLI workflow. Check `inheriti version` and `inheriti help` for the installed build; commands vary by Business deployment and feature flags. Read only the reference for the task at hand. The CLI handles sign-in, governance, custody, and progress; the agent supplies non-secret context and interprets safe status.
11
11
 
@@ -13,6 +13,8 @@ Turn the user's requested outcome into the smallest supported CLI workflow. Chec
13
13
  2. Identify **where** the result is needed: a person's clipboard or file, a local child process, a verified workload, or a persistent provider secret store. Choose the command from that destination, not from an application name. For example, Terraform may run locally or in a workload; inspect its actual execution path before choosing delivery.
14
14
  3. Preview the exact plan, selected fields, executable, file, workload, mappings, or cloud destination before a consequential action. Let the CLI and user complete its own prompts and approvals. Verify with safe metadata or status; never request a secret value in chat or capture it from clipboard, command output, logs, or a file.
15
15
 
16
- Use [identity and discovery](references/identity-and-discovery.md) for login, Organisation selection, plan lookup, versions, and diagnostics. For plan creation or metadata, read [plans and inspection](references/plans-create-and-inspect.md). For field access, files, and cancellation, read [reveal and files](references/reveal-and-files.md). To run a program with plan fields, read [process delivery](references/process-delivery.md). For connection and grant lifecycle, read [automations](references/automations.md), then the relevant section of [provider workflows](references/automation-providers.md). Read [troubleshooting](references/troubleshooting.md) when a flow fails or pauses.
16
+ Use [identity and discovery](references/identity-and-discovery.md) for login, Organisation selection, plan lookup, versions, and diagnostics. For plan creation or metadata, read [plans and inspection](references/plans-create-and-inspect.md). For field access, files, and cancellation, read [reveal and files](references/reveal-and-files.md). To run a program with plan fields, read [process delivery](references/process-delivery.md). For connection and grant lifecycle, including a guided prompt copied from Business, read [automations](references/automations.md), then the relevant section of [provider workflows](references/automation-providers.md). Read [troubleshooting](references/troubleshooting.md) when a flow fails or pauses.
17
+
18
+ For automations, preserve any Organisation, plan, provider, destination, member, and connection already supplied. Establish the intended cloud account/profile and region or project before discovering resources; use [provider workflows](references/automation-providers.md) to identify a specific target. A resource appearing in a list does not establish intent.
17
19
 
18
20
  Do not place secret values, custody shares, proofs, private keys, or bearer tokens in prompts, CLI arguments, shell history, environment setup, provider settings, or agent-visible output. `secrets resolve` is a special trusted-pipe API, not a way for the agent to read a value. Avoid `--output inherit` unless the user explicitly accepts the child program's logs. A natural-language request does not replace a plan's approval or authorise an unrelated deployment.
@@ -1,26 +1,34 @@
1
1
  # Automation providers and runtime
2
2
 
3
- Read only the section for the workload that will actually execute the protected process. Use `inheriti help automations create`, `pair`, `setup`, and `runtime` for exact options in the installed build. Operator-side `gh`, `gcloud`, or AWS CLI authentication permits discovery and setup; the runtime identity must still be the identity configured on the connection.
3
+ Read only the section for the workload that will actually execute the protected process. Use `inheriti help automations create`, `pair`, `setup`, and `runtime` for exact options in the installed build. Operator-side `gh`, `gcloud`, or AWS CLI authentication permits discovery and setup; the runtime identity must still be the identity configured on the connection. Discover only in the chosen account/profile and region or project, then pass that same context to the Inheriti® CLI. Offer safe names/IDs when several candidates exist and let the user choose; a single result is not an implicit selection. List and inspect only projected non-secret metadata; never print an unfiltered `describe-*` response or full workload configuration, which may contain environment values. For AWS, keep `AWS_PROFILE=PROFILE AWS_REGION=REGION` identical on every `aws` and `inheriti` subprocess, including preview and installation; for example, `AWS_PROFILE=PROFILE AWS_REGION=REGION inheriti automations setup ...`.
4
4
 
5
5
  ## GitHub Actions
6
6
 
7
- Bind `automations create --provider GITHUB` to the exact `--repository OWNER/REPO`, job `--environment NAME`, and `--workflow OWNER/REPO/.github/workflows/FILE.yml@refs/heads/BRANCH`. The job needs `id-token: write` and the audience returned by the CLI. The CLI does not create a repository or initial pairing job. After proof verification and an active grant, `automations usage --plan PLAN_ID --connection CONNECTION_ID --field ASSET.FIELD` emits YAML pinned to a Business-verified Action and CLI release; it refuses to emit a workflow when that release is unavailable. Put it in the exact repository/file/ref it names, then verify the run through safe plan logs.
7
+ Identify the intended repository, environment, workflow file, and ref before binding `automations create --provider GITHUB` to the exact `--repository OWNER/REPO`, job `--environment NAME`, and `--workflow OWNER/REPO/.github/workflows/FILE.yml@refs/heads/BRANCH`. The job needs `id-token: write` and the audience returned by the CLI. The CLI does not create a repository or initial pairing job. After proof verification and an active grant, `automations usage --plan PLAN_ID --connection CONNECTION_ID --field ASSET.FIELD` emits YAML pinned to a Business-verified Action and CLI release; it refuses to emit a workflow when that release is unavailable. Put it in the exact repository/file/ref it names, then verify the run through safe plan logs.
8
+
9
+ For an unknown workflow in a selected repository, `gh workflow list --repo OWNER/REPO` can show candidates; confirm the intended environment and ref separately.
8
10
 
9
11
  ## Google Cloud Run service or job
10
12
 
11
- Bind `--provider GOOGLE_CLOUD` to a stable non-secret `--audience-base URI`, `--project`, `--region`, and one of `--service` or `--job`. The CLI can inspect the attached service account numeric ID with the local Google Cloud CLI; the service/job must exist. The runtime image needs the Inheriti CLI before pairing. `automations pair google` launches a temporary job with the source identity after checking the generation and image. After grant activation, `automations setup` previews the selected service/job and field mappings; `--apply` updates that exact workload with a reviewed image/revision. It does not create a Cloud Run resource.
13
+ In the chosen project and region, identify the intended Cloud Run service or job, then bind `--provider GOOGLE_CLOUD` to a stable non-secret `--audience-base URI`, `--project`, `--region`, and one of `--service` or `--job`. The CLI can inspect the attached service account numeric ID with the local Google Cloud CLI; the service/job must exist. The runtime image needs the Inheriti® CLI before pairing. `automations pair google` launches a temporary job with the source identity after checking the generation and image. After grant activation, `automations setup` needs the application's explicit startup configuration and previews the selected service/job and field mappings; `--apply` updates that exact workload with a reviewed image/revision. Choose `--container` if more than one container exists. A pairable workload may still need startup configuration before setup. It does not create a Cloud Run resource.
14
+
15
+ For discovery, use `gcloud run services list --project PROJECT --region REGION` or `gcloud run jobs list --project PROJECT --region REGION`; confirm the active account and configuration, and avoid full workload JSON that may contain environment values.
12
16
 
13
17
  ## AWS ECS
14
18
 
15
- Bind `--provider AWS` to `--region`, `--cluster`, and an existing `--service` or `--task-definition`. Use the **task role**, never `executionRoleArn`; the CLI can resolve the role from the existing workload. For multiple containers, choose `--container`. The image must include the CLI. `automations pair aws` can run a temporary ECS task, pinning the inspected task definition and image digest; it does not change the service. After an active grant, `automations setup` previews the runtime update and requires explicit `--apply` with a reviewed image/revision to change the ECS service.
19
+ In the chosen AWS account/profile and region, identify the intended ECS cluster and service or task definition, then bind `--provider AWS` to `--region`, `--cluster`, and an existing `--service` or `--task-definition`. Use the **task role**, never `executionRoleArn`; the CLI can resolve the role from the existing workload. For multiple containers, choose `--container`. The image must include the CLI. `automations pair aws` can run a temporary ECS task, pinning the inspected task definition and image digest; it does not change the service. After an active grant, `automations setup` previews the runtime update and requires an actual service and explicit `--apply` with a reviewed image/revision to change the ECS service. A lone task definition can be paired but has no managed service to update.
20
+
21
+ Confirm the chosen identity with `AWS_PROFILE=PROFILE aws sts get-caller-identity`; discover within its region with `AWS_PROFILE=PROFILE aws ecs list-clusters --region REGION`, then `AWS_PROFILE=PROFILE aws ecs list-services --cluster CLUSTER --region REGION`. Do not disable pagination; inspect only non-secret fields of a chosen service/task definition. Use the identical subprocess-scoped environment for identity, discovery, and Inheriti® CLI, with `AWS_PROFILE=PROFILE` and the same region. Exported session credentials can override that profile: verify the returned Account/Arn matches the intended account and stop on a mismatch; do not silently switch or clear credentials. Do not mix discovery using `aws --profile` with Inheriti® CLI using only `AWS_PROFILE`, because their credential precedence differs.
16
22
 
17
23
  ## AWS EC2
18
24
 
19
- For an application directly on an instance, bind the connection to `--region` and `--instance`; the attached instance-profile role is the identity. `automations runtime install ec2 --region REGION --instance INSTANCE_ID` uses SSM to install and verify the exact published CLI version on an online Linux instance. Confirm instance, region, and version before remote installation. `automations pair ec2` uses SSM for `pair redeem` and checks the attached role. `automations setup` previews the launcher and systemd unit; `--install` writes them after confirmation but does not start the service. Do not mistake an EC2 instance for an ECS service.
25
+ For an application directly on an instance, identify the intended region and instance, and verify its attached instance-profile role matches the connection identity. Bind the connection to `--region` and `--instance`; the attached instance-profile role is the identity. `automations runtime install ec2 --region REGION --instance INSTANCE_ID` uses SSM to install and verify the exact published CLI version on an online Linux instance. Confirm instance, region, and version before remote installation. `automations pair ec2` uses SSM for `pair redeem` and checks the attached role. Before remote actions, check that the instance is Linux and online in SSM. `automations setup` requires the actual `--service-name NAME --run-as-user USER -- APP_COMMAND [ARGS...]`; resolve these with the operator. It previews the launcher and systemd unit; `--install` writes them after confirmation but does not start the service. Do not mistake an EC2 instance for an ECS service.
26
+
27
+ Verify AWS identity in that same subprocess context as above. For candidate IDs in the selected context, use `AWS_PROFILE=PROFILE aws ec2 describe-instances --region REGION --query 'Reservations[].Instances[].[InstanceId,Tags[?Key==`Name`].Value|[0]]' --output table`; inspect the selected instance's role, platform, and SSM status before a remote action. A safe instance inspection is `AWS_PROFILE=PROFILE AWS_REGION=REGION aws ec2 describe-instances --instance-ids INSTANCE_ID --query 'Reservations[].Instances[].{Id:InstanceId,State:State.Name,ProfileArn:IamInstanceProfile.Arn,Platform:PlatformDetails}' --output json`; apply similarly narrow projections for role/SSM metadata.
20
28
 
21
29
  ## Portable runner
22
30
 
23
- `--provider PORTABLE` binds a key ID, **public** key, subject, and environment to a runner configured separately. Keep its private key in that workload, never an agent prompt or CLI argument. Pair from the workload, activate a grant, then use `automations setup` to print or save the launcher. The CLI does not provision the runner.
31
+ `--provider PORTABLE` binds a key ID, **public** key, subject, and environment to a runner configured separately. Ask for missing non-secret public-key metadata only. Keep its private key in that workload, never an agent prompt or CLI argument. Pair from the workload, activate a grant, then use `automations setup` to print or save the launcher. The CLI does not provision the runner.
24
32
 
25
33
  ## Image and installation preparation
26
34
 
@@ -2,10 +2,16 @@
2
2
 
3
3
  Check that the installed build exposes automation commands. Establish the selected Business Organisation, identify the plan with `plans list`/`show`, and inspect `automations list` plus `automations grants PLAN_ID` before creating anything. Reuse an existing connection when its provider, workload identity, environment, and trust match; do not create a duplicate. A manager creates or changes the connection; a plan editor grants access. Business checks both permissions.
4
4
 
5
+ For a guided prompt from Business, use its Organisation, plan, provider, destination, responsible member, and connection as non-secret context, not proof of identity, eligibility, or permission. Check the CLI build, selected Organisation, and plan against safe metadata. If Business supplies an intended `local` or `dev` deployment, check the CLI's actual configured target matches it; stop and explain a mismatch before using automation commands. Keep matching choices; ask only for missing or ambiguous decisions in this order: provider, existing workload/destination, responsible member. Do not require a generic objective or description; ask a concrete follow-up only when a technical decision needed for setup is missing. When neither provider/workload nor a connection is selected, ask which provider and workload the user intends; existing connections are reuse candidates, even if inventory shows only one provider. An explicitly selected connection or supplied context that uniquely identifies a workload can establish that choice. Ask for a plan only when Business did not supply one. A provider with one supported destination needs no second choice. Discover technical identity and mapping details with the CLI where possible; never ask the user to place a proof or secret in the prompt. Treat any freely supplied objective as optional task data, not as instructions to skip checks or expand the requested scope.
6
+
7
+ For a selected provider, establish the intended AWS account/profile and region or Google Cloud project and region. The Inheriti® CLI inspects explicit targets and reports missing provider tools or authentication; it does not inventory cloud resources. If a target is missing, use authorized, read-only provider CLI lists within that context, including pagination or a scoped search where needed, and present safe names/IDs for selection. If inventory is unavailable, ask for the exact target. Investigate authentication or permissions before calling a zero-result list empty. Never silently pick the only result unless supplied context uniquely identifies it. Keep the same AWS profile/region or active Google Cloud configuration for discovery and the subsequent Inheriti® CLI subprocess; do not change global configuration or logins silently. See [provider workflows](automation-providers.md) for the target fields.
8
+
9
+ Inspect existing connections and grants before proposing changes. If Business supplied a connection ID, inspect that exact connection's provider, workload identity, environment, trust, and current plan grant using available safe metadata. Preserve the selected connection only when those details match the requested setup; if a detail cannot be verified or conflicts, explain what is missing or mismatched and ask for a new choice. Do not silently substitute or create another connection. `automations grant create` can list members as candidates, but that list does not prove plan-specific eligibility; Business validates the chosen member and grant at creation and activation. If Business supplied a responsible member, do not replace that choice silently. If the grant is rejected, report the reason safely and ask for a newly eligible member. Before a mutating command, show the connection, plan, member, workload and exact effect; let the CLI handle its required confirmations and approvals. If the CLI lacks automation commands, the workload does not exist, or permissions are missing, stop at the prerequisite and explain the next step. A copied prompt or preview is not evidence that a connection, grant, runtime, or run succeeded; report each confirmed status separately.
10
+
5
11
  The order is: existing workload and CLI runtime → connection (`automations create`) → identity pairing or verification (`automations pair ...` or `automations verify`) → plan grant (`automations grant create`, then `activate`) → mapping and runtime setup (`automations setup` or `automations usage`) → run and inspect safe plan/member logs. `automations trust` changes the non-secret identity policy and may require reverification; `automations disable` stops a connection. `automations grant member` changes its responsible member; `revoke` ends a grant. Present the exact connection, plan, member, and effect before these changes. Never pass a workload proof, private key, or credential as an argument or through chat.
6
12
 
7
13
  `automations pair start [--connection ID]` opens a ten-minute window; `pair redeem` runs inside the configured workload and sends a fresh native proof directly to Business. Provider helpers can pair a temporary ECS task, Cloud Run job, or SSM-managed EC2 instance after target/revision inspection and confirmation. `automations verify` opens a native proof-entry window only when there is already a secure transfer route; it does not fetch proof from Cloud Run or ECS. Review the provider-specific route in [provider workflows](automation-providers.md).
8
14
 
9
- `automations setup --plan PLAN_ID --connection CONNECTION_ID ...` maps plan fields to runtime inputs. Use `--map-all` with optional `--except`, repeatable `--only`, or `--map NAME=ASSET.FIELD`; inspect the complete mapping before action. It can print or save a launcher for a custom/container runner, preview a managed ECS/Cloud Run change, or prepare an EC2 launcher and systemd unit. Cloud changes require an explicit `--apply` with a prepared image and reviewed target revision; EC2 writes require `--install` and confirmation. The CLI does not invent or create an app, repository, workload, IAM role, or cloud account. `automations usage` generates a GitHub workflow only for a verified connection, active grant, and Business-verified Action/CLI release.
15
+ `automations setup --plan PLAN_ID --connection CONNECTION_ID ...` maps plan fields to runtime inputs. Select each needed `ASSET.FIELD` with repeatable `--only` and use `--map NAME=ASSET.FIELD` for an application variable; inspect the complete mapping before action. Use `--map-all` only when the user explicitly wants every eligible field. It can print or save a launcher for a custom/container runner, preview a managed ECS/Cloud Run change, or prepare an EC2 launcher and systemd unit. Cloud changes require an explicit `--apply` with a prepared image and reviewed target revision; EC2 writes require `--install` and confirmation. The CLI does not invent or create an app, repository, workload, IAM role, or cloud account. `automations usage` generates a GitHub workflow only for a verified connection, active grant, and Business-verified Action/CLI release.
10
16
 
11
17
  For an application that already reads a provider secret store, `secrets publish aws|google` previews exact field-to-destination mappings and applies only with `--apply`. This is a **one-time copy**: later plan edits or revocation do not rotate or delete the provider copy. Prefer direct `secrets exec --automation` inside a verified workload when ongoing plan control is intended. Check `inheriti help secrets publish aws|google` for current target flags; never put values in them.
@@ -1,6 +1,6 @@
1
1
  # Identity and discovery
2
2
 
3
- Run `inheriti help` or `inheriti help COMMAND SUBCOMMAND` before using an unfamiliar command; `inheriti version` reports the installed build. `inheriti update` checks its channel, while `inheriti update --install` installs an offered build after confirmation. A required Business CLI update is checked after login and before authenticated commands. The bundled skill is reconciled automatically with the CLI; a running agent may need a new session to load the updated instructions. `inheriti setup` configures shell autocomplete, and `inheriti completion bash|zsh|fish` prints a completion script; neither is needed to install this skill.
3
+ Run `inheriti help` or `inheriti help COMMAND SUBCOMMAND` before using an unfamiliar command; `inheriti version` reports the installed build. `inheriti update` checks its channel, while `inheriti update --install` installs an offered build after confirmation. A required Business CLI update is checked after login and before authenticated commands. The bundled skill is reconciled automatically when the CLI detects a supported Codex home; a running agent may need a new session to load the updated instructions. `inheriti setup` configures shell autocomplete, and `inheriti completion bash|zsh|fish` prints a completion script; neither is needed to install this skill.
4
4
 
5
5
  `inheriti login` opens a browser and needs an interactive terminal. `inheriti logout` clears the local operator session, not plans. In Business, run `inheriti organizations list` to see eligible Organisations and the selected one; use `inheriti organizations use [ID]` to select. If more than one Organisation could contain the requested plan, establish the right one before searching or changing anything. The CLI and server enforce membership and permissions.
6
6
 
@@ -8,5 +8,8 @@
8
8
  - **Reveal pending:** report the CLI's current gate and the device or person who must act. Wait for the outcome; do not reissue a second reveal merely because an approval is slow. Denial, reconciliation, and DMS stop have distinct outcomes. `plans abort` resets an open operator access only when requested.
9
9
  - **Clipboard/file issue:** inspect the reported delivery status. TTL cleanup is best effort; downloads do not overwrite and may require a protected `.inheriti` path. Never read the value back to “verify” it.
10
10
  - **Automation pairing expired or workload changed:** inspect connection status and the live workload identity/revision, then start a new pairing window if still intended. Do not reuse a proof or ignore an expected-revision mismatch.
11
+ - **Provider CLI unavailable or unauthenticated:** follow the Inheriti® CLI's `aws_cli_required`, `gcloud_cli_required`, `aws_authentication_required`, or `gcloud_authentication_required` message and its safe `providerDiagnostic`. Ask the operator to install or authenticate locally in the intended account/profile or project; never ask for credentials or proof in chat. An access-denied diagnostic needs the specific read or action permission, not a different guessed target.
12
+ - **Cloud inventory has no results:** confirm the selected context, list pagination, and read permissions before concluding it is empty. If discovery remains unavailable, ask for the exact instance, cluster/service, service/job, or workflow rather than searching unrelated accounts or regions.
13
+ - **Remote command times out or outcome is unclear:** inspect any returned command/run ID and live provider state before retrying. Report the operation as pending or unconfirmed until verified; do not claim success or failure from a timeout alone.
11
14
  - **Grant, mapping, or deployment failed:** compare the chosen plan, responsible member, connection, field selectors, and preview. Verify safe logs and provider state; do not claim deployment from a generated launcher alone.
12
15
  - **Update required:** complete the CLI's verified update, rerun in the new process, and start a new agent session if its bundled skill changed. Skill reconciliation uses local bundled files; it does not require a separate manual install step.
@@ -1 +1 @@
1
- {"schema":1,"cliVersion":"0.0.21-dev.0","deployment":"dev","sha256":"21f5074ac19546172a75311c1a77d79e6b5307b7926e1672b3ce0dc630635ef0"}
1
+ {"schema":1,"cliVersion":"0.0.22-dev.0","deployment":"dev","sha256":"4fe13cfd3e9734a3dc23f3cff5bd202f3b9d83638a9c555f8a4fd8a6dce8f7e6"}