Self CLI

A CLI for managing and administering self applications.

Device and Key management

Every identity on the self network connects through a device with its own set of cryptographic keys. These devices can send and receive messages, as well as sign statements and attestations.

When you create an application through the developer portal, it will automatically generate you a device key (SELF_APP_DEVICE_SECRET), as well as a recovery key. These need to be stored somewhere safe and never shared with anyone.

The device key generated by the portal can then be used to connect to self via the SDK. You will be required to pass this key to the SDK's configuration as SELF_APP_DEVICE_SECRET.

From the CLI, you will be able to create new devices, rotate a devices keys or revoke an existing device. You can also recover your account by using a recovery key.

Considerations

Please ensure that all keys generated by this CLI tool are stored somewhere safe.

As device keys are tied to end to end encrypted sessions, you will be required to clear out any existing session or account .pickle files that you have in your self storage folder when rotating or replacing a devices keys.

Available commands

All commands require you to provide one of your secret device keys, as well as your app identifier. The key you provide must be valid and not revoked.

$ self-cli -h

List all devices

To list all devices and their status:

$ self-cli device list --secret-key MY-SECRET-DEVICE-KEY [appID]

Create a new device

With this command, you are able to create a new device that can connect to the self network. Once this device has been created, it will be marked as active and available for receiving requests from other identities.

To create a new device, you will need to run the following command and provide a valid device secret key. A new device key will be generated for you:

$ self-cli device create --secret-key MY-SECRET-DEVICE-KEY [appID]

If you wish you provide your own public key, you may create a device as follows:

$ self-cli device create --secret-key MY-SECRET-DEVICE-KEY --device-public-key MY-NEW-DEVICE-PUBLIC-KEY [appID]

Revoke an existing device

Should you need to prevent an existing device from accessing the self network, you can revoke it's keys.

To revoke an existing device:

$ self-cli device revoke --secret-key MY-SECRET-DEVICE-KEY --effective-from 1607607355 [appID] [deviceID]

If your device key becomes compromised and you wish to retroactively revoke a device, you can specify a Unix timestamp of when you want the revocation to take place:

$ self-cli device revoke --secret-key MY-SECRET-DEVICE-KEY --effective-from 1607607355 [appID] [deviceID]

Rotate a devices keys

If you wish to replace the existing keys for a device with a new set, you can run the following:

$ self-cli device rotate --secret-key MY-SECRET-DEVICE-KEY [appID] [deviceID]

If you wish to provide the public key for the device yourself, you can run:

$ self-cli device rotate --secret-key MY-SECRET-DEVICE-KEY --device-public-key MY-NEW-DEVICE-PUBLIC-KEY [appID] [deviceID]

Account recovery

If you have lost access to your account and wish to recover your account, you can use the following command. It will revoke all existing keys for your account and create you a new device and recovery keypair:

$ self-cli identity recover --recovery-key MY-SECRET-RECOVERY-KEY [appID]