speatzle/go-passbolt-cli
1
0
Fork 0
mirror of https://github.com/passbolt/go-passbolt-cli.git synced 2025-09-13 14:59:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge 8d19b3c94a into 9c2c25aa7d

Browse source
This commit is contained in:
Marc Würth 2025-09-09 17:12:04 +02:00 • committed by GitHub
commit 7ce5dc536e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 75 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

115
README.md
View file

@ -1,124 +1,157 @@
# go-passbolt-cli # go-passbolt-cli
A CLI tool to interact with Passbolt, an Open source Password Manager for teams.
If you want to do something more complicated: [this Go Module](https://github.com/passbolt/go-passbolt) to Interact with Passbolt from Go might intrest you. A CLI tool to interact with [Passbolt](https://www.passbolt.com), an open source password manager for teams.
If you want to do something more complicated: [this Go module](https://github.com/passbolt/go-passbolt) to interact with Passbolt from Go might interest you.
Disclaimer: This project is community driven and not associated with [Passbolt SA](https://www.passbolt.com/about).
Disclaimer: This project is community driven and not associated with Passbolt SA
# Install # Install
## Via Repository (Preferred): ## Via Repository (Preferred):
[![Packaging status](https://repology.org/badge/vertical-allrepos/go:passbolt-cli.svg)](https://repology.org/project/go:passbolt-cli/versions) [![Packaging status](https://repology.org/badge/vertical-allrepos/go:passbolt-cli.svg)](https://repology.org/project/go:passbolt-cli/versions)
Use the package from your Distros Official Repository Use the package from your distros official repository.
## Via Package: ## Via Package:
Download the deb/rpm Package for your Distro and architecture from the Latest Release.
Install via your Distros Package manager like `dpkg -i` Download the deb/rpm package for your distro and architecture from the latest release.
Install via your distros package manager like `dpkg -i`.
## Via Homebrew ## Via Homebrew
brew install passbolt/tap/go-passbolt-cli brew install passbolt/tap/go-passbolt-cli
## Via Archive: ## Via Archive:
Download and Extract the Archive for your OS and architecture from the Latest Release.
Note: tab completion and manpages will need to be installed manually. Download and extract the archive for your OS and architecture from the latest release.
Note: Tab completion and manpages will need to be installed manually.
## Via Go: ## Via Go:
go install github.com/passbolt/go-passbolt-cli@latest go install github.com/passbolt/go-passbolt-cli@latest
Note: this will install the binary as go-passbolt-cli, also tab completion and manpages will be missing.
Note: This will install the binary as `go-passbolt-cli`. Also, tab completion and manpages will be missing.
# Getting Started # Getting Started
First you need to Setup basic information: the Server Address, your Private Key and your Password.
First, you need to set up basic information:
- The server address,
- your private key
- and your password/passphrase.
You have these options: You have these options:
- Save it in the config file using - Save it in the config file using
``` ```
passbolt configure --serverAddress https://passbolt.example.org --userPassword '1234' --userPrivateKeyFile 'keys/privatekey.asc' passbolt configure --serverAddress https://passbolt.example.org --userPassword '1234' --userPrivateKeyFile 'keys/privatekey.asc'
``` ```
or or
``` ```
passbolt configure --serverAddress https://passbolt.example.org --userPassword '1234' --userPrivateKey '-----BEGIN PGP PRIVATE KEY BLOCK-----' passbolt configure --serverAddress https://passbolt.example.org --userPassword '1234' --userPrivateKey '-----BEGIN PGP PRIVATE KEY BLOCK-----'
``` ```
- Setup Environment Variables
- Provide the Flags manually every time - Set up environment variables
- Provide the flags manually every time
Notes: Notes:
- You can set the Private Key using the flags `--userPrivateKey` or `--userPrivateKeyFile` where `--userPrivateKey` takes the actual private key and `--userPrivateKeyFile` loads the content of a file as the PrivateKey, `--userPrivateKeyFile` overwrites the value of `--userPrivateKey`.
- You can also just store the serverAddress and your Private Key, if your Password is not set it will prompt you for it every time. - You can set the private key using the flags `--userPrivateKey` or `--userPrivateKeyFile` where `--userPrivateKey` takes the actual private key and `--userPrivateKeyFile` loads the content of a file as the private key, `--userPrivateKeyFile` overwrites the value of `--userPrivateKey`.
- Passwordless PrivateKeys are unsupported - You can also just store the `serverAddress` and your private key. If your password is not set it will prompt you for it every time.
- MFA settings can also be save permanently this ways - Passwordless private keys are not supported.
- MFA settings can also be saved permanently this way.
# Usage # Usage
Generally the Structure of Commands is like this: Generally, the structure of commands are like this:
```bash ```bash
passbolt action entity [arguments] passbolt action entity [arguments]
``` ```
Action is the Action you want to perform like Creating, Updating or Deleting an Entity. `action` is the action you want to perform like creating, updating or deleting an entity.
Entity is a Resource(Password), Folder, User or Group that you want to apply an action to. `entity` is a resource (e.g. password), folder, user or group that you want to apply an action to.
In Passbolt a Password is usually revert to as a Resource. In Passbolt a password is usually referred to as a "resource".
To create a resource you can do the following, which will return the ID of the newly created resource:
To Create a Resource you can do this, it will return the ID of the newly created Resource:
```bash ```bash
passbolt create resource --name "Test Resource" --password "Strong Password" passbolt create resource --name "Test Resource" --password "Strong Password"
``` ```
You can then list all users: You can then list all users:
```bash ```bash
passbolt list user passbolt list user
``` ```
Note: you can adjust which columns should be listed using the flag `--column` or its short from `-c`, if you want multiple column then you need to specify this flag multiple times.
Note: You can adjust which columns should be listed using the flag `--column` or its short from `-c`,
if you want multiple column then you need to specify this flag multiple times.
For sharing we will need to know how we want to share, for that there are these Permission Types: For sharing, we will need to know how we want to share, for that there are these permission types:
| Code | Meaning | | Code | Meaning |
| --- | --- | |------|----------------------------|
| `1` | "Read-only" | | `1` | Read-only |
| `7` | "Can update" | | `7` | Can update |
| `15` | "Owner" | | `15` | Owner |
| `-1` | Delete existing permission | | `-1` | Delete existing permission |
Now that we have a Resource ID, know the ID's of other Users and about know about Permission Types, we can share the Resource with them: Now, that we have a resource ID, know the IDs of other users and know about permission types, we can share the resource with them:
```bash ```bash
passbolt share resource --id id_of_resource_to_share --type type_of_permission --user id_of_user_to_share_with passbolt share resource --id id_of_resource_to_share --type type_of_permission --user id_of_user_to_share_with
``` ```
Note: you can supply the the users argument multiple times to share with multiple users
Note: You can supply the users argument multiple times to share with multiple users.
For sharing with groups the `--group` argument exists. For sharing with groups the `--group` argument exists.
# MFA # MFA
You can setup MFA also using the configuration sub command, only TOTP is supported, there are multiple modes for MFA: `none`, `interactive-totp` and `noninteractive-totp`.
| Mode | Description |
| --- | --- |
|`none`|just errors if challenged for MFA.
|`interactive-totp` | prompts for interactive entry of TOTP Codes.
|`noninteractive-totp` | automatically generates TOTP Codes when challenged, it requires the `mfaTotpToken` flag to be set to your totp Secret, you can configure the behavior using the `mfaDelay`, `mfaRetrys` and `mfaTotpOffset` flags
You can set up MFA also using the configuration sub command. Only TOTP is supported. There are multiple modes for MFA: `none`, `interactive-totp` and `noninteractive-totp`.
| Mode | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none` | just errors if challenged for MFA. |
| `interactive-totp` | prompts for interactive entry of TOTP Codes. |
| `noninteractive-totp` | automatically generates TOTP codes when challenged. It requires the `mfaTotpToken` flag to be set to your TOTP secret. You can configure the behavior using the `mfaDelay`, `mfaRetrys` and `mfaTotpOffset` flags |
# Server Verification # Server Verification
To enable Server Verification you need to run `passbolt verify` once, after that the server will always be verified if the same config is used
To enable server verification, you need to run `passbolt verify` once, after that the server will always be verified if the same config is used.
# Scripting # Scripting
For Scripting we have a -j or --json flag to convert the Output for the create, get and list commands to JSON for easier Parsing in Scripts.
Note: The JSON Output does not cover Error Messages, you can detect Errors by checking if the Exitcode is not 0 For scripting we have a `-j` or `--json` flag to convert the output for the `create`, `get` and `list` commands to JSON for easier parsing in scripts.
Note: The JSON output does not cover error messages. You can detect errors by checking if the exit code is not 0.
# Exposing Secrets to Subprocesses # Exposing Secrets to Subprocesses
The `exec` command allows you to execute another command with environment variables that reference secrets stored in Passbolt. The `exec` command allows you to execute another command with environment variables that reference secrets stored in Passbolt.
Any environment variables containing `passbolt://` references are automatically resolved to their corresponding secret values Any environment variables containing `passbolt://` references are automatically resolved to their corresponding secret values
before the specified command is executed. This ensures that secrets are securely injected into the child process's environment before the specified command is executed. This ensures that secrets are securely injected into the child process's environment
without exposing them to the parent shell. without exposing them to the parent shell.
For example: For example:
```bash ```bash
export GITHUB_TOKEN=passbolt://<PASSBOLT_RESOURCE_ID_HERE> export GITHUB_TOKEN=passbolt://<PASSBOLT_RESOURCE_ID_HERE>
passbolt exec -- gh auth login passbolt exec -- gh auth login
``` ```
This would resolve the passbolt:// reference in GITHUB_TOKEN to its actual secret value and pass it to the gh process. This would resolve the `passbolt://` reference in `GITHUB_TOKEN` to its actual secret value and pass it to the GitHub process.
# Documentation # Documentation
Usage for all Subcommands is [here](https://github.com/passbolt/go-passbolt-cli/wiki/passbolt).
And is also available via `man passbolt`
Usage for all subcommands is [here](https://github.com/passbolt/go-passbolt-cli/wiki/passbolt).
And is also available via `man passbolt`