At protocol CLI
npm install @substrate-system/at





A typescript/node CLI client for at protocol (bluesky).
This exposes a CLI tool, at, that you can use to make requests to
your DID document.
Contents
- Install
- Use
* aka command
+ Example
+ Using a custom PDS
* did command
+ Arguments
+ Example
* rotation command
+ Arguments
+ Example: Add a key
+ Example: Remove a key
- How it works
``sh`
npm i @substrate-system/at
Add a URL to your DID's alsoKnownAs property.
The aka command lets you link external URLs, like Github,
to your Bluesky DID document. See
verify.aviary.domains
to lookup your DID document and see the also known as values.
If you did not install this glabally via npm i -g @substrate-system/at,npx
then use to execute it.
`bash`
npx at aka
Arguments
- - Your Bluesky handle (e.g., alice.bsky.social)
- - The URL to link (e.g., https://github.com/alice)--pds
- - (Optional) Custom PDS server URL. Defaults to https://bsky.social
#### Example
Link to your github profile.
`sh`
at aka alice.bsky.social https://github.com/alice
This command will:
1. Prompt you for your Bluesky password
2. Send a verification code to your email
3. Ask you to enter the verification code
4. Update your DID document so that it includes your GitHub URL in
the alsoKnownAs property
The resulting alsoKnownAs array in your DID document will contain:
`js`
[
"at://alice.bsky.social",
"https://github.com/alice"
]
#### Using a custom PDS
Pass in the --pds argument with PDS URL.
`sh`
at aka alice.example.com https://alice.com --pds https://pds.example.com
Fetch the DID document for a given handle or DID string.
``
npx at did
#### Arguments
- - A Bluesky handlealice.bsky.social
(e.g., or @alice.bsky.social) or a DID stringdid:plc:abc123
(e.g., )--pds
- - (Optional) Custom PDS server URL for handle resolution.https://bsky.social
Defaults to . Not used when passing a DID directly.--log
- , -l - (Optional) Fetch the audit log instead of the DID document.did:plc:
Only available for identifiers, not did:web.
#### Example
Get a DID document by handle:
`sh`
npx at did @nichoth.com
Or pass a DID string directly:
`sh`
npx at did did:plc:s53e6k6sirobjtz5s6vdddwr
`js`
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1",
"https://w3id.org/security/suites/secp256k1-2019/v1"
],
"id": "did:plc:s53e6k6sirobjtz5s6vdddwr",
"alsoKnownAs": [
"at://nichoth.com",
"https://github.com/nichoth/"
],
"verificationMethod": [
{
"id": "did:plc:s53e6k6sirobjtz5s6vdddwr#atproto",
"type": "Multikey",
"controller": "did:plc:s53e6k6sirobjtz5s6vdddwr",
"publicKeyMultibase": "zQ3shnSayXqCvnetx9S5BaHVEXPovHqpKcXwK2oRwAWPVKmdz"
}
],
"service": [
{
"id": "#atproto_pds",
"type": "AtprotoPersonalDataServer",
"serviceEndpoint": "https://lionsmane.us-east.host.bsky.network"
}
]
}
Extract fields using jq:
`shGet the DID string
npx at did alice.bsky.social | jq -r '.id'=> did:plc:vdjlpwlhbnug4fnjodwr3vzh
Output
Returns a JSON object containing:
-
id - The DID identifier
- alsoKnownAs - Array of alternative identifiers
- verificationMethod - Cryptographic keys for the identity
- service - Service endpoints (like the PDS server)Audit Log
Use the
--log or -l flag to fetch the audit log for a DID from the PLC directory. This shows the history of changes to the DID document:`sh
npx at did @nichoth.com --log
or
npx at did did:plc:s53e6k6sirobjtz5s6vdddwr --log
`The audit log returns an array of operations with their CIDs and timestamps:
`js
[
{
"cid": "bafyreid...",
"nullified": false,
"operation": {
"type": "plc_operation",
"services": { ... },
"alsoKnownAs": [...],
// ... other operation details
},
"createdAt": "2024-01-15T10:30:00.000Z"
},
// ... previous operations
]
`$3
Add or remove a rotation key. This will require you to verify the operation
by clicking an email.`
npx at rotation [key] [--pds ] [--format ] [--remove ]
`#### Arguments
-
- Your Bluesky handle (e.g., alice.bsky.social)
- [key] - (Optional) The private key (in hex format) for the new rotation key.
If not provided, a new keypair will be generated.
- --pds - (Optional) Custom PDS server URL. Defaults to https://bsky.social
- --format, -f - (Optional) Output format for the generated keypair: json
(default), hex, or jwk.
- --remove, -rm - (Optional) Remove the given rotation key.
Pass the public key in multikey format (e.g., did:key:z...) or just
the key part (e.g., z...).
#### Example: Add a key
Generate a new keypair and add it as a rotation key:
`sh
at rotation alice.bsky.social
`This will:
1. Generate a new secp256k1 keypair
2. Log in and request email verification
3. Add the new public key to your DID document's
rotationKeys
4. Print the new private key (save this securely!)You can also provide an existing private key in hex format:
`
at rotation alice.bsky.social
`#### Example: Remove a key
Remove an existing rotation key from your account:
`sh
at rotation alice.bsky.social --remove "did:key:zQ3sh..."
`You can also pass just the key part:
`sh
at rotation alice.bsky.social --remove "zQ3sh..."
`This command will:
1. Log in and request email verification
2. Fetch the current rotation keys from the PLC directory
3. Remove the specified key from the list
4. Update your DID with the new list of rotation keys
How it works
The AT Protocol uses DID (Decentralized Identifier)
documents as user identity. Each DID can include an
alsoKnownAs` field that links to other identifiers or URLs.This uses the
@atproto/api client.