Metadata-Version: 2.4
Name: intflow-authctl
Version: 0.2.1
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.
