Skip to content

Commit

Permalink
chore: updated vaults commands
Browse files Browse the repository at this point in the history
  • Loading branch information
@aryanjassal
aryanjassal committed Dec 24, 2024
1 parent dbf3997 commit b2601b2
Show file tree
Hide file tree
Showing 3 changed files with 123 additions and 140 deletions.
118 changes: 60 additions & 58 deletions docs/reference/polykey-cli/commands/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,18 @@ The bootstrap subcommand solely deals with the construction of the state of poly
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)].

| Command | Description | Level | Interaction |
| --------- | ----------------------------------------- | ----- | ----------- |
| bootstrap | Initializes a PolyKey node at a node path | 1 | Local |
|-----------|-------------------------------------------|-------|-------------|
| bootstrap | Initializes a Polykey node at a node path | 1 | Local |

### Agent

The agent subcommand allows control over the Polykey agent process.

| Command | Description | Level | Interaction |
| ------- | --------------------------------------- | ----- | ----------- |
| start | Starts the PolyKey Agent | 1 | Local |
| stop | Stops the PolyKey Agent | 1 | Local |
| status | Gets the status of the PolyKey Agent | 1 | Local |
|---------|-----------------------------------------|-------|-------------|
| start | Starts the Polykey Agent | 1 | Local |
| stop | Stops the Polykey Agent | 1 | Local |
| status | Gets the status of the Polykey Agent | 1 | Local |
| unlock | Starts a session for the current client | 1 | Local |
| lock | Locks the current client session | 1 | Local |
| lockall | Locks all active sessions on the agent | 1 | Local |
Expand All @@ -39,38 +39,38 @@ The agent subcommand allows control over the Polykey agent process.

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

| Command | Description | Level | Interaction |
| ----------- | ----------------------------------- | ----- | ----------- |
| create | Creates a new vault | 1 | Local |
| delete | Deletes an existing vault | 1 | Local |
| list | Lists all existing vaults | 1 | Local |
| rename | Renames an existing vault | 1 | Local |
| stats | Gets the stats of an existing vault | 1 | Local |
| share | Shares vaults with a gestalt | 1 | Local |
| unshare | Unshares vaults with a gestalt | 1 | Local |
| permissions | Gets the permissions for a vault | 1 | Local |
| pull | Pulls a vault from another node | 1 | Agent-Agent |
| scan | Lists the vaults of another node | 1 | Agent-Agent |
| clone | Clones a vault from another node | 1 | Agent-Agent |
| Command | Description | Level | Interaction |
|--------------|-------------------------------------|-------|-------------|
| create | Creates a new vault | 1 | Local |
| rm \| remove | Removes an existing vault | 1 | Local |
| ls \| list | Lists all existing vaults | 1 | Local |
| rename | Renames an existing vault | 1 | Local |
| stats | Gets the stats of an existing vault | 1 | Local |
| share | Shares vaults with a gestalt | 1 | Local |
| unshare | Unshares vaults with a gestalt | 1 | Local |
| permissions | Gets the permissions for a vault | 1 | Local |
| pull | Pulls a vault from another node | 1 | Agent-Agent |
| scan | Lists the vaults of another node | 1 | Agent-Agent |
| clone | Clones a vault from another node | 1 | Agent-Agent |

### Secrets

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.

| Command | Description | Level | Interaction |
| ------- | ------------------------------------------------ | ----- | ----------- |
| create | Creates a new secret | 1 | Local |
| delete | Deletes an existing secret | 1 | Local |
| edit | Edits an existing secret | 1 | Local |
| get | Gets the contents of an existing secret | 1 | Local |
| list | Lists the secrets within an existing vault | 1 | Local |
| mkdir | Makes a directory inside an existing vault | 1 | Local |
| dir | Adds a directory of secrets to an existing vault | 1 | Local |
| rename | Renames an existing secret | 1 | Local |
| update | Updates an existing secret with new content | 1 | Local |
| env | Injects existing secrets into an environment | 2 | Local |
| Command | Description | Level | Interaction |
|--------------|-----------------------------------------------------------------------|-------|-------------|
| create | Creates a new secret | 1 | Local |
| rm \| remove | Removes an existing secret | 1 | Local |
| ed \| edit | Edits an existing secret or creates one if it doesn't exist | 1 | Local |
| cat | Gets the contents of one or more secrets | 1 | Local |
| ls \| list | Lists the secrets within an existing directory | 1 | Local |
| mkdir | Makes a directory inside an existing vault | 1 | Local |
| dir | Adds a directory of secrets to an existing vault | 1 | Local |
| rename | Renames an existing secret | 1 | Local |
| write | Updates an existing secret with new content taken from standard input | 1 | Local |
| env | Injects existing secrets into an environment | 2 | Local |

### Keys

Expand All @@ -83,7 +83,7 @@ Encryption using the root keypair has a size limit depending on the size of the
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.

| Command | Description | Level | Interaction |
| --------- | ------------------------------------------- | ----- | ----------- |
|-----------|---------------------------------------------|-------|-------------|
| cert | Gets the root certificate | 1 | Local |
| certchain | Get the certificate chain | 1 | Local |
| root | Get the root keypair | 1 | Local |
Expand All @@ -99,38 +99,40 @@ For signature and verification using the root keypair, the data and signature wi

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

| Command | Description | Level | Interaction |
| --------------- | ---------------------------------------- | ----- | ----------- |
| add | Adds a node to the node graph | 1 | Local |
| delete(Removed) | Deletes a node from the node graph | 1 | Local |
| get(Removed) | Gets the node info for a particular node | 1 | Local |
| claim | Makes a claim to a node | 1 | Agent-Agent |
| unclaim | Removes a claim to a ndoe | 1 | Agent-Agent |
| find | Attempts to find a node in the DHT | 1 | Agent-Agent |
| ping | Pings a node to check if it is online | 1 | Agent-Agent |
| Command | Description | Level | Interaction |
|-------------|---------------------------------------|-------|-------------|
| add | Adds a node to the node graph | 1 | Local |
| connections | Lists all active node connections | 1 | Agent |
| claim | Makes a claim to a node | 1 | Agent-Agent |
| find | Attempts to find a node in the DHT | 1 | Agent-Agent |
| ping | Pings a node to check if it is online | 1 | Agent-Agent |
| getall | Gets all nodes from the node graph | 1 | Agent-Agent |

### Identities

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

| Command | Description | Level | Interaction |
| ------------ | ------------------------------------------------------------------- | ----- | ----------- |
| claim | Claim an identity for this keynode | 1 | Local |
| authenticate | Authenticate a social identity provider (Github only) | 1 | Local |
| get | Gets the gestalt of a node or identity | 1 | Local |
| list | Lists the available gestalts | 1 | Local |
| trust | Trusts a node id or identity | 1 | Local |
| untrust | Untrusts a node id or identity | 1 | Local |
| search | Searches the provider for a connected identity | 1 | Local |
| allow | Set a specific permission for a Node or Identity | 2 | Local |
| disallow | Remove a Specific permission for a Node or Identity | 2 | Local |
| discover | Starts discovery process using Node or Identity as a starting point | 1 | Agent-Agent |
| perms | Gets the permisson for an node or identity | 1 | Local |
| Command | Description | Level | Interaction |
|---------------|---------------------------------------------------------------------|-------|-------------|
| claim | Claim an identity for this keynode | 1 | Local |
| authenticate | Authenticate a social identity provider (Github only) | 1 | Local |
| get | Gets the gestalt of a node or identity | 1 | Local |
| list | Lists the available gestalts | 1 | Local |
| trust | Trusts a node id or identity | 1 | Local |
| untrust | Untrusts a node id or identity | 1 | Local |
| search | Searches the provider for a connected identity | 1 | Local |
| allow | Set a specific permission for a node or an identity | 2 | Local |
| disallow | Remove a specific permission for a node or identity | 2 | Local |
| discover | Starts discovery process using node or identity as a starting point | 1 | Agent-Agent |
| permissions | Gets the permission for a node or an identity | 1 | Local |
| queue | Prints out vertices queued for discovery | 1 | Local |
| invite | Invites another keynode | 1 | Local |
| authenticated | Lists all authenticated identities across all providers | 1 | Local |

### Notifications

| Command | Description | Level | Interaction |
| ------- | ----------------------------------------------- | ----- | ----------- |
|---------|-------------------------------------------------|-------|-------------|
| send | Sends a notification to another node | 1 | Agent-Agent |
| read | Displays notifications and marks them as "read" | 1 | Local |
| clear | Clears all read and unread notifications | 1 | Local |
Expand All @@ -139,10 +141,10 @@ The identities subcommand allows control over the node's identity and its links

- Toggles should be `-f` `-v` flags that when used are `true` and when not used are `false`. These can be joined up together like `-fv`, but this may be confusing with the multiword options, and in which case I usually don't use the joined up versions. Flags should be sparing, users should not need to remember every flag they need to do something.
- Options should ideally be optional `--key value` and `-k value`. In some cases they represent key-value parameters which are not optional. Make sure that multi-word options are like `--multi-word` and their short form is `-mw`.
- Parameters should be positional so `pk subcommand param1 param2`, in that case they are usually not optional and are required, it is possible to have arbitrary arity of parameters so you can have 1, or many.
- Exception is `pk subcommand -k value -k2 value -k3 value`, which is a key value parameters, this would not be optional, but in many cases if the commands are designed well, you should be able to have all values as parameters.
- Parameters should be positional so `polykey subcommand param1 param2`, in that case they are usually not optional and are required, it is possible to have arbitrary arity of parameters so you can have 1, or many.
- Exception is `polykey subcommand -k value -k2 value -k3 value`, which is a key value parameters, this would not be optional, but in many cases if the commands are designed well, you should be able to have all values as parameters.

Make sure you're using the output formatting functions in the `src/bin/utils.ts` (or at least that's where I had them last). This ensures you have a consistent set outputs, whether it is a list, table, json or otherwise. We can have `-f` to indicate different output formats for these.
Make sure you're using the output formatting functions in the `src/bin/utils.ts`. This ensures you have a consistent set outputs, whether it is a list, table, json or otherwise. We can have `-f` to indicate different output formats for these.

And for testing, try to use the `main` exported function, but I think as you said on slack there are new methods that make it easier to test these that might have been created by @DrFacepalm or @scottmmorris.

Expand Down
4 changes: 2 additions & 2 deletions docs/reference/polykey-cli/commands/secrets.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## `create`
1. Create a secret within a given vault
2. Requires a filepath as input which contains the secret
2. Requires a file path as input which contains the secret


Usage:
Expand Down Expand Up @@ -81,7 +81,7 @@ I edited this secret inside an editor
4. If no paths are specified, this command takes input from `stdin` and prints it to `stdout`

:::tip
`^D` in the terminal stands for the button 'Ctrl-D'
`^D` in the terminal stands for the key combination 'Ctrl-D'
:::

Usage:
Expand Down
Loading

0 comments on commit b2601b2

Please sign in to comment.