# Community Network Manager (CNM) CLI
The CNM CLI is the primary client for operating a
[Verifiable Trust Agent (VTA)](../README.md) and participating in
[Verifiable Trust Communities](https://www.firstperson.network/white-paper).
It provides authentication, key management, access control, and
multi-community support from a single command-line tool.
## Table of Contents
- [Feature Flags](#feature-flags)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Multi-Community Support](#multi-community-support)
- [Authentication](#authentication)
- [Configuration](#configuration)
- [CLI Reference](#cli-reference)
- [Additional Resources](#additional-resources)
## Feature Flags
| `keyring` | Store sessions in the OS keyring (macOS Keychain, GNOME Keyring, Windows Credential Manager) | Yes |
| `config-session` | Store sessions in `~/.config/cnm/sessions.json`. Useful for containers and CI where no keyring is available. **Warning:** sessions are stored on disk unprotected -- do not use in production. | No |
At least one of `keyring` or `config-session` must be enabled. When `keyring`
is enabled it takes priority over `config-session`.
### Build examples
```sh
# Default build (keyring)
cargo build --package cnm-cli --release
# Keyring-free build for containers / CI
cargo build --package cnm-cli --release --no-default-features --features config-session
```
## Installation
### From source
Requires **Rust 1.91.0+**.
```sh
cargo build --package cnm-cli --release
```
The binary is at `target/release/cnm`.
### During development
All examples below use `cnm` directly. When developing from the workspace,
substitute `cargo run --package cnm-cli --` for `cnm`.
## Quick Start
### 1. Run the setup wizard
The setup wizard walks you through connecting to your first community:
```sh
cnm setup
```
The wizard prompts for:
1. **Personal VTA URL** and **credential** -- your personal VTA instance.
2. **Community name**, **slug**, and **VTA URL** -- the community you want to join.
3. **Join method** -- import an existing credential from a community admin, or
generate a DID via your personal VTA and request access.
Configuration is saved to `~/.config/cnm/config.toml`.
### 2. Verify connectivity
```sh
cnm health
```
### 3. Start using the CLI
```sh
# List application contexts
cnm contexts list
# Create a signing key
cnm keys create --key-type ed25519 --context-id myapp --label "Signing Key"
# List keys
cnm keys list
```
## Multi-Community Support
CNM supports connecting to multiple communities simultaneously. Each community
has its own VTA service, credentials, and session stored independently in the
OS keyring.
### Add a community
```sh
# Interactive wizard
cnm community add
```
### List communities
```sh
cnm community list
```
### Switch the default community
```sh
cnm community use <slug>
```
### Override community per-command
```sh
cnm -c acme keys list
```
### Show active community status
```sh
cnm community status
```
### Remove a community
```sh
cnm community remove <slug>
```
## Authentication
CNM uses **DID-based challenge-response authentication** with short-lived JWT
tokens:
1. **Import a credential** -- a base64-encoded bundle containing your client
DID, private key, and the community's VTA DID.
2. **Challenge-response** -- the CLI requests a nonce from the VTA, signs a
DIDComm v2 message, and receives a JWT.
3. **Token caching** -- tokens are cached in the OS keyring and refreshed
automatically when they expire.
```sh
# Import credential and authenticate
cnm auth login <credential>
# Check auth status
cnm auth status
# Clear credentials
cnm auth logout
```
After initial login, all subsequent commands authenticate transparently.
### Credential storage
With the default `keyring` feature, sessions are stored in the platform's
credential manager:
| macOS | Keychain |
| Linux | secret-service (e.g. GNOME Keyring) |
| Windows | Credential Manager |
When built with `--features config-session` (and without `keyring`), sessions
are stored in `~/.config/cnm/sessions.json` instead. See
[Feature Flags](#feature-flags) for details.
## Configuration
### Config file
`~/.config/cnm/config.toml`
```toml
default_community = "storm"
[personal_vta]
url = "https://personal.vta.example.com"
[communities.storm]
name = "Storm Network"
url = "https://vta.storm.ws"
context_id = "cnm-storm-network"
vta_did = "did:webvh:..."
[communities.acme]
name = "Acme Corp"
url = "https://vta.acme.example.com"
# vta_did and context_id are optional
```
### VTA service configuration
```sh
# View current VTA config
cnm config get
# Update VTA metadata
cnm config update --community-vta-name "My VTA" --public-url "https://vta.example.com"
```
### Environment variables
| `VTA_URL` | Override the VTA base URL |
| `RUST_LOG` | Set log level (e.g. `debug`, `info`) |
## CLI Reference
### Global flags
| `--url <URL>` | Override VTA base URL (or set `VTA_URL`) |
| `-c, --community <slug>` | Override active community for this command |
| `-v, --verbose` | Enable debug logging |
### Setup & Communities
| `setup` | Interactive first-time setup wizard |
| `community list` | List configured communities |
| `community use <slug>` | Set default community |
| `community add` | Add a new community interactively |
| `community remove <slug>` | Remove a community |
| `community status` | Show active community info and auth status |
### Authentication
| `auth login <credential>` | Import credential and authenticate |
| `auth logout` | Clear stored credentials and tokens |
| `auth status` | Show current authentication status |
### Health
| `health` | Check VTA service health, resolve DIDs, show endpoints |
### Configuration
| `config get` | Show current VTA configuration |
| `config update [options]` | Update VTA metadata (DID, name, description, URL) |
### Keys
| `keys list [--status active\|revoked] [--limit N] [--offset N]` | List keys |
| `keys create --key-type ed25519\|x25519 [--context-id ID] [--label LABEL]` | Create a key |
| `keys get <key_id>` | Get a key by ID |
| `keys revoke <key_id>` | Revoke a key |
| `keys rename <key_id> <new_key_id>` | Rename a key |
| `keys secrets [key_ids...] [--context ID]` | Export secret key material |
| `keys seeds` | List seed generations |
| `keys rotate-seed [--mnemonic PHRASE]` | Rotate to a new seed |
### Contexts
| `contexts list` | List application contexts |
| `contexts get <id>` | Get a context by ID |
| `contexts create --id ID --name NAME [--description DESC]` | Create a context |
| `contexts update <id> [--name ...] [--did ...] [--description ...]` | Update a context |
| `contexts delete <id>` | Delete a context |
| `contexts bootstrap --id ID --name NAME [--admin-label LABEL]` | Create context + first admin credential |
### ACL
| `acl list [--context ID]` | List ACL entries |
| `acl get <did>` | Get an ACL entry by DID |
| `acl create --did DID --role ROLE [--label LABEL] [--contexts ctx1,ctx2]` | Create an ACL entry |
| `acl update <did> [--role ROLE] [--label LABEL] [--contexts ctx1,ctx2]` | Update an ACL entry |
| `acl delete <did>` | Delete an ACL entry |
Roles: `admin`, `initiator`, `application`. An admin with no contexts listed
has unrestricted access across all contexts.
### Auth Credentials
| `auth-credential create --role ROLE [--label LABEL] [--contexts ctx1,ctx2]` | Generate a did:key credential with ACL entry |
## Additional Resources
- [VTA Service & Architecture](../README.md)
- [PNM CLI (single-VTA)](../pnm-cli/README.md) -- simpler alternative for personal use
- [First Person Network White Paper](https://www.firstperson.network/white-paper)
- [Design Document](../docs/design.md)
- [BIP-32 Path Specification](../docs/bip32_paths.md)