Metadata-Version: 2.4
Name: intflow-authctl
Version: 0.2.2
Summary: Intflow Auth operator CLI.
Author: Intflow
License: Proprietary
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Requires-Dist: keyring<26,>=25
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: hatchling==1.31.0; extra == 'dev'
Requires-Dist: mypy<3,>=1.13; extra == 'dev'
Requires-Dist: packaging<27,>=24; extra == 'dev'
Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
Requires-Dist: pytest-timeout<3,>=2.4; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# intflow-authctl

`intflow-authctl` is the Python operator CLI package for Intflow Auth.

## Install

```powershell
py -3.12 -m pip install --user --upgrade intflow-authctl
```

## CLI

```powershell
intflow-authctl login
intflow-authctl whoami
intflow-authctl users list
intflow-authctl tokens create-no-expiry
intflow-authctl clients list
intflow-authctl clients rotate-secret <oauth-client-id> --grace-seconds 0
intflow-authctl logout --revoke
```

The CLI is intended for authorized Intflow operators. It manages local operator
credentials through the supported credential backends and communicates with an
Intflow Auth deployment over the Admin API.

After CLI login, an `admin`-role user can run `tokens create-no-expiry` to
verify the current CLI identity and open the browser-only issuance page on the
same Auth service. Use `--no-browser` to print the URL only. The CLI bearer token
is never added to the URL or passed to the browser.

Failed commands return a nonzero exit code and write a bounded diagnostic to
stderr. Admin HTTP failures include only the status, a validated service error
code when present, and bounded `Retry-After` guidance. Upstream descriptions,
malformed bodies, credentials, and raw transport causes are not rendered.
Automation should parse JSON stdout only after a successful command.

## Package Scope

This distribution contains only the operator CLI, Admin API client, output and
validation logic, and credential-store adapters. It does not contain the Auth
service, database models, migrations, or service bootstrap commands.

## Requirements

- Python 3.12 or later.
- Access to an authorized Intflow Auth deployment.


## Discover commands and diagnose access

No repository checkout is needed to explore the installed CLI:

```text
intflow-authctl --help
intflow-authctl docs
intflow-authctl login
intflow-authctl doctor
intflow-authctl clients create --help
intflow-authctl users find --help
```

Every command has `--help`, including nested commands. `docs` works offline and
prints onboarding guidance plus links to the API documentation and OpenAPI.
`docs --open` opens the documentation only when requested; use `--base-url` for
a different Auth deployment. `doctor` makes one read-only `whoami` request and
shows the current identity, effective scopes and token metadata without printing
the bearer token. Missing/expired credentials return exit code 2 with login guidance.

A company account does not automatically grant Auth management access. A 403
explains the required token scope where known, but server roles and target
restrictions still apply. When using `login --scope`, repeat it for **all** needed
scopes; it replaces the default scope selection. `logout --revoke` requires
`admin:tokens:write`; if remote revocation fails, local credentials remain.

## Save a client secret without printing it

```text
intflow-authctl clients create --name "Internal app" --client-type confidential --redirect-uri https://app.example/callback --scope openid --scope email --scope profile --secret-file /private/new-client.json
intflow-authctl clients rotate-secret CLIENT_ID --grace-seconds 60 --secret-file /private/new-rotation.json
```

Choose a new file in a private existing directory outside the repository. The
file contains the complete response JSON, including `client_secret`; stdout
contains metadata and `client_secret_file` instead. The CLI refuses to overwrite
an existing file and protects the empty file **before** contacting the server
(POSIX 0600; Windows current-user DACL with inherited access removed).
If storage fails after the server changes the client, inspect the client and
rotate to a working destination; do not repeat creation. Without `--secret-file`,
the existing one-time secret JSON output remains unchanged. Transfer the file
through your approved secret delivery mechanism and remove it when no longer needed.

Public clients cannot hold secrets. Use confidential clients for trusted backends,
register exact callback URLs, and use PKCE S256. Add `offline_access` only when
refresh tokens are needed. App administrator assignment is a separate operation.

## Recovery and local diagnostics

`intflow-authctl --version` identifies the installed version and distribution.
`doctor` remains read-only; `doctor --check-store` explicitly tests local storage
with a temporary nonsecret write/read/delete probe and needs no login or server.
Login runs the same preflight before requesting browser approval.

Login polling honors server intervals and bounded HTTP 429 Retry-After guidance.
It does not retry transport failures or 5xx responses, because one-time redemption
may already have succeeded. Re-login never revokes server tokens. It removes only
a previous local entry owned by the same config; legacy/shared entries are retained
with a warning to preserve other profiles. Local logout can clear a config whose
keyring entry is already missing. Use `logout --revoke` for explicit remote revocation.

`tokens create --name automation --ttl 1h --secret-file /private/new-token.json`
stores the full one-time response in a new protected file and returns `token_file`
instead of the bearer. Without that option, existing one-time JSON stdout is unchanged.
If issuance succeeds but storage fails, inspect and explicitly revoke the unused
token before repeating issuance. File output uses the same protections as client secrets.
