Metadata-Version: 2.4
Name: secflow-cli
Version: 0.2.2
Summary: SecFlow operator CLI
License-Expression: MIT
Project-URL: Repository, https://github.com/yeon3724/secflow
Project-URL: Issues, https://github.com/yeon3724/secflow/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: secflow-sdk==0.1.8
Requires-Dist: keyring<26,>=25
Dynamic: license-file

# SecFlow CLI

Use Intflow browser login or an existing Slack-issued Admin session. Both distributions provide the same `secflowctl` commands.

## Install and update

Choose one distribution per machine; both own the same `secflowctl` command and share profiles and the OS credential store.

```sh
pipx install secflow-cli
# Or in a Python environment:
python -m pip install secflow-cli

# Alternative: Node.js 22+; no separate Python installation required
npm install --global @intflow/secflow-cli
secflowctl --version
```

The Python distribution requires Python 3.10+. Installation automatically includes the Admin-capable `secflow-sdk==0.1.8` dependency.

The npm distribution includes Python and the CLI dependencies in OS-specific native packages. Initial targets: Windows x64, macOS Intel/Apple Silicon, and Linux x64 with glibc 2.35+ (Ubuntu 22.04+). Alpine/musl and Linux ARM are not npm targets yet; use the Python distribution there. Keep npm optional dependencies enabled. Installation has no postinstall script or runtime download. Native binaries are not platform-signed or notarized.

The bundled interpreter includes CA certificates for HTTPS. An explicit `SSL_CERT_FILE` or `SSL_CERT_DIR` takes precedence for organization-managed trust; TLS certificate verification stays enabled.

```sh
pipx upgrade secflow-cli
# Or use the same installer as the initial installation:
python -m pip install --upgrade secflow-cli
npm install --global @intflow/secflow-cli@latest
```

## Connect

```sh
secflowctl login
secflowctl auth status
secflowctl namespaces list --help
secflowctl namespaces list --all
secflowctl --help
```

`secflowctl` without arguments displays a quick start. `secflowctl login` opens Intflow login and creates the `production` profile for `https://secflow.intflow.dev` on first use. Existing profiles retain their selected server. For another server, first use `secflowctl profile add staging --base-url https://secflow.example.test`, then `secflowctl --profile staging login`. Global options precede the command. Every command supports `--help`, including examples. Account and role administration requires server authorization.

`auth login` remains compatible with Slack-issued Admin sessions and prompts without echo for an existing session. Sessions are stored in Windows Credential Manager, macOS Keychain, or Linux Secret Service. Linux persistent login needs an unlocked Secret Service (for example GNOME Keyring) and a D-Bus session. If secure storage is unavailable, login fails without a plaintext file fallback. Installing the CLI does not create an account or grant access.

When browser login is enabled on the server, run `secflowctl auth login --browser`. Sign in to Intflow, compare the code with your terminal, and approve the SecFlow login. Use `--browser --no-browser` to open the displayed URL manually. This requires an interactive terminal, an existing authorized SecFlow account, and OS credential storage. The CLI stores only the resulting SecFlow session. If login expires or the exchange fails, start a new login.

For automation use `SECFLOW_ADMIN_SESSION_TOKEN` supplied by your secret manager, or `--token-stdin` with `--non-interactive`. Never put tokens in command arguments, profiles, shell history, or tracked files. SDK tokens cannot authorize these Admin commands. `auth logout` revokes the current server session; `auth forget` only removes the local credential.

To uninstall, use `pipx uninstall secflow-cli`, `python -m pip uninstall secflow-cli`, or `npm uninstall --global @intflow/secflow-cli` as appropriate. Uninstalling does not revoke server sessions or erase profiles; log out and remove unwanted profiles first.

## Expanded commands in 0.2.0

CLI 0.2.0 adds the commands below. Metadata catalogs, details, permission checks, and per-secret access changes require the additive operator APIs on the server. An older server can still serve existing commands. `auth status` reports expiry and capabilities on newer servers and falls back to identity-only metadata when the session endpoint is absent. Authorization or dependency failures are not treated as an old server.

| Task | Discover commands |
| --- | --- |
| Identity, permissions, service state | `auth status`, `auth capabilities`, `health`, `dashboard` |
| Find authorized targets | `catalog accounts`, `catalog namespaces`, `catalog token-accounts`, `catalog actors` |
| Account and namespace details | `accounts get --help`, `namespaces get --help` |
| Namespace members and scoped roles | `namespaces members list`, `add`, `remove`; `roles list --namespace` or `--account-id` |
| Delete impact | `namespaces impact`, `accounts impact`; `delete` shows the same counts before confirming |
| Secret lifecycle | `secrets create`, `get`, `list`, `update`, `rotate`, `activate-revision`, `delete`; inspect each with `--help` |
| Direct secret access overrides | `secrets access list`, `grant`, `block`, `reset`; reset restores inherited access |
| SDK tokens and Admin sessions | `tokens issue --help`, `tokens revoke --help`, `auth sessions issue --help` |
| Policies | `policies list`, `get`, `draft`, `preview`, `put`, `templates list`, `templates build` |
| Audit metadata | `audit events list --help`, `audit exports --help` |
| SDK access diagnostics | `runtime validate`, `metadata`, `permission-check`, `revoke-leases` |
| Offline reference preparation | `refs build`, `validate`, `prepare`, `list`, `remove` |
| Diagnostics | `doctor`; `doctor --watch --interval 60 --count 30` emits one JSONL record per run |
| Metadata reports | `reports tokens`, `reports rotation`, `reports access --namespace` |
| Repeatable setup | `manifest export`, `manifest plan`, `manifest apply` (see below) |
| Shell completion | `completion bash`, `zsh`, or `powershell` |

Without saved profiles, `secflowctl health` checks the default production origin without logging in or writing a profile. Use `--base-url` before `health` to select another origin. An explicitly selected profile must exist. Collection commands support bounded pagination where shown in help; audit events have a maximum page size of 100.

## Repeat namespace setup

```sh
secflowctl manifest export --namespace dev/example > manifest.json
# Edit owners, audit logging, expiration policy, or members (account_id + secret_reader/secret_writer).
secflowctl --profile staging manifest plan --file manifest.json > plan.json
secflowctl --profile staging manifest apply --file plan.json
```

A manifest covers namespace metadata and namespace members only; it never holds secret values, tokens, or policies, and it never deletes a namespace. `plan` changes nothing; `--prune` also revokes members missing from the manifest. A plan is bound to the server it was made for and cannot be edited. `apply` re-reads each item first: an item already in the desired state is skipped, and an item whose current state differs from the plan stops the run with exit 6. After an interruption or an uncertain result (exit 8), run the same `apply` again; it resumes and retries with each item's original idempotency key. Earlier items stay applied; nothing is rolled back.

## Review and replace a policy

First find the active policy with `secflowctl policies list --namespace dev/example`. Then use its ID:

```sh
secflowctl policies get --namespace dev/example --policy-id POLICY_UUID > current.json
secflowctl policies draft --file current.json > draft.json
# Edit draft.json's data.rules, preserving rules that must remain active.
secflowctl policies preview --file draft.json
secflowctl policies put --file draft.json
```

Draft creation is offline. It preserves scope and rules, generates a new policy ID, and increments the version. `put` still submits the supplied policy unchanged: it replaces the complete active policy for that scope. Do not reuse the current policy ID for a new revision. UTF-8, UTF-8 BOM, and BOM-marked UTF-16 files from Windows PowerShell redirection are accepted. Raw API policy JSON and successful CLI get/draft/template-build envelopes are supported.

To append a template rule without discarding existing rules:

```sh
secflowctl policies templates list
secflowctl policies templates build --file current.json --template runtime_read --account-id ACCOUNT_UUID --ref secret://dev/example/token/primary > draft.json
secflowctl policies preview --file draft.json
secflowctl policies put --file draft.json
```

Template building reads the authorized server catalog and writes only a draft. The SecretRef must belong to the policy namespace; existing deny rules still take precedence. Preview validates a document without saving it and does not prove future authorization or protect against concurrent policy changes. There is no server compare-and-swap precondition: review the latest active policy and coordinate concurrent edits before replacing it.

For automation, use `--non-interactive` before the command and `--yes` on `put`. Keep the exact draft file and the idempotency key printed to stderr for an identical retry. Do not generate another draft or key when a mutation outcome is uncertain.

## Credentials and values

`tokens issue --save-as NAME` stores an SDK token separately from Admin profiles; `runtime ... --sdk-name NAME` uses it. `auth sessions issue --save-as PROFILE` creates a new destination profile. Both require a new destination name or explicit `--token-stdout` to redirected stdout; raw credentials never appear in ordinary JSON/table results. Linux/macOS non-interactive invocations require an explicitly injected credential rather than unlocking the OS store.

Secret create/rotate reads exact UTF-8 or base64 input through hidden input, `--value-stdin`, or `--value-file`. Do not put values in command arguments. Stdin cannot simultaneously carry an Admin token and a secret or policy document. Runtime commands use SDK credentials only; Admin sessions are never substituted. No plaintext resolve command is provided.
