astrid-runtime/astrid · error

--scope=shared is only valid for manifest-declared secrets

Error message

--scope=shared is only valid for manifest-declared secrets

What it means

`run_set` only permits `--scope=shared` for values whose kind is a manifest-declared secret. Text-typed values must stay in the default Agent scope, so any non-Agent scope on a Text value bails here. This prevents storing non-secret, machine-local text in the shared scope.

Source

Thrown at crates/astrid-cli/src/commands/secret.rs:321

        .unwrap_or(EnvValueKind::Text);
    let secret_declared = kind == EnvValueKind::Secret;

    if args.scope.is_some() && !secret_declared {
        anyhow::bail!(
            "--scope requires the capsule manifest to declare '{}' as type=\"secret\" \
             (manifest declares either a non-secret env field, or no field at all for this key)",
            args.key
        );
    }

    let scope = args
        .scope
        .map_or(EnvStorageScope::Agent, |scope| match scope {
            ScopeArg::Agent => EnvStorageScope::Agent,
            ScopeArg::Shared => EnvStorageScope::Shared,
        });
    if matches!(kind, EnvValueKind::Text) && !matches!(scope, EnvStorageScope::Agent) {
        anyhow::bail!("--scope=shared is only valid for manifest-declared secrets");
    }
    let mut client = crate::admin_client::connect_as_active_agent().await?;
    let body = client
        .request(AdminRequestKind::EnvSet {
            principal: principal.clone(),
            capsule: capsule.to_string(),
            key: args.key.clone(),
            value: args.value.clone(),
            kind,
            scope,
            append: false,
        })
        .await?;
    crate::admin_client::into_result(body)?;
    println!(
        "{}",
        Theme::success(&format!(
            "Stored '{}' for agent '{}' (capsule {})",

View on GitHub (pinned to affd8760f4)

Solutions

1. Remove `--scope` (defaults to Agent) if the value is a plain text env var.
2. Declare the key as `type = "secret"` in the capsule manifest if it truly must be shared.
3. Check the manifest env section to confirm the key's declared type before choosing a scope.

Example fix

// before
astrid secret set --agent dev --capsule web --key PORT --scope shared --value 8080
// after
astrid secret set --agent dev --capsule web --key PORT --value 8080

// only pass --scope for manifest-declared secrets
if grep -q "type = \"secret\"" <(grep -A2 "${KEY}" capsule.toml); then
  SCOPE="--scope shared"
else
  SCOPE=""
fi
astrid secret set --key "$KEY" $SCOPE --value "$VAL"

When it happens

Trigger: `astrid secret set --scope shared --key FOO` where capsule_env_kind resolved FOO to EnvValueKind::Text (manifest declares it as text or has no secret declaration).

Common situations: Copying a working command for a secret and reusing it for a plain env var; misunderstanding that --scope=shared works for all env values; editing the manifest to change a secret to text while still passing --scope=shared.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• --scope requires the capsule manifest to declare '{key}' as
• invalid key: must not be empty
• durable capsule {} has malformed contracts pin
• refusing to seed canonical from a non-content-address contra
• --retain-entries must be at least 1

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/4b70f61224f470ff. Report an issue: GitHub.