Skip to main content


Similar to Polykey, the CLI commands will be divided into 7 domains which reflect functions that can be performed within specific sections of the program.

There are 3 levels which indicate the personas that would use each command. The first level represents a new user who will not directly interact with encryption but rather will primarily use the vault system. The second and third levels indicate users who will use cryptography commands beyond the existing vault system.

The node path is optionally supplied to all commands and will indicate the polykey node to use. If no path is specified, the default path is used.

There are no 'lock' or 'unlock' commands. Polykey is unlocked through one of two methods. Each command will specify an optional password parameter. Entering a password directly into the CLI is insecure as the CLI history can reveal the password. Therefore a file containing the password must be supplied to the command. This will create a session with a timeout of 5 minutes. If no commands are entered within the 5 minute timer, then the session is destroyed and the password must be entered again. The other method for creating a session will occur when no session exists and a CLI command is executed. A prompt will appear for the password to be entered, which will create a session if entered successfully. A session with a Polykey Agent is a singleton, so only one session can be used with an Agent at anytime.


The bootstrap subcommand solely deals with the construction of the state of polykey.

The supplied or assumed node path must exist and be empty for a successful execution, otherwise the command will exit with code [EX_USAGE (64)].

bootstrapInitializes a PolyKey node at a node path1Local


The agent subcommand allows control over the Polykey agent process.

startStarts the PolyKey Agent1Local
stopStops the PolyKey Agent1Local
statusGets the status of the PolyKey Agent1Local
unlockStarts a session for the current client1Local
lockLocks the current client session1Local
lockallLocks all active sessions on the agent1Local


The vaults subcommand will deal with CRUD (Create, read, update and delete) operations on Polykey vaults.

createCreates a new vault1Local
deleteDeletes an existing vault1Local
listLists all existing vaults1Local
renameRenames an existing vault1Local
statsGets the stats of an existing vault1Local
shareShares vaults with a gestalt1Local
unshareUnshares vaults with a gestalt1Local
permissionsGets the permissions for a vault1Local
pullPulls a vault from another node1Agent-Agent
scanLists the vaults of another node1Agent-Agent
cloneClones a vault from another node1Agent-Agent


The secrets subcommand will deal with CRUD (Create, read, update and delete) operations on secrets within a Polykey vault.

As secrets subcommands are performed within a single vault, paths are specified using the following notation <vaultName>:<secretPath>. As each vault maintains separate filesystems, secrets cannot be transferred across vaults.

createCreates a new secret1Local
deleteDeletes an existing secret1Local
editEdits an existing secret1Local
getGets the contents of an existing secret1Local
listLists the secrets within an existing vault1Local
mkdirMakes a directory inside an existing vault1Local
dirAdds a directory of secrets to an existing vault1Local
renameRenames an existing secret1Local
updateUpdates an existing secret with new content1Local
envInjects existing secrets into an environment2Local


The keys subcommand will deal with operations using the root keypair and root certificate.

Keys database is an internal implementation for storing keys from other domains and currently cannot be manipulated by users.

Encryption using the root keypair has a size limit depending on the size of the public key.

For signature and verification using the root keypair, the data and signature will be input and output separately. In the future, this will be done using a specific file format which allows the signature and data to be compiled into one file.

certGets the root certificate1Local
certchainGet the certificate chain1Local
rootGet the root keypair1Local
renewRenews the root keypair1Local
passwordChange the password of the root keypair1Local
resetResets the root keypair2Local
decryptDecrypts data using the root keypair2Local
encryptEncrypts data using the root keypair2Local
signSigns data using the root keypair3Local
verifyVerifies a signature using the root keypair3Local


The node subcommand allows manipulation of Polykey's peer-to-peer system.

addAdds a node to the node graph1Local
delete(Removed)Deletes a node from the node graph1Local
get(Removed)Gets the node info for a particular node1Local
claimMakes a claim to a node1Agent-Agent
unclaimRemoves a claim to a ndoe1Agent-Agent
findAttempts to find a node in the DHT1Agent-Agent
pingPings a node to check if it is online1Agent-Agent


The identities subcommand allows control over the node's identity and its links with other social identities.

claimClaim an identity for this keynode1Local
authenticateAuthenticate a social identity provider (Github only)1Local
getGets the gestalt of a node or identity1Local
listLists the available gestalts1Local
trustTrusts a node id or identity1Local
untrustUntrusts a node id or identity1Local
searchSearches the provider for a connected identity1Local
allowSet a specific permission for a Node or Identity2Local
disallowRemove a Specific permission for a Node or Identity2Local
discoverStarts discovery process using Node or Identity as a starting point1Agent-Agent
permsGets the permisson for an node or identity1Local


sendSends a notification to another node1Agent-Agent
readDisplays notifications and marks them as "read"1Local
clearClears all read and unread notifications1Local