Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/1Password/op-js
A JS library powered by the 1Password CLI
https://github.com/1Password/op-js
Last synced: about 23 hours ago
JSON representation
A JS library powered by the 1Password CLI
- Host: GitHub
- URL: https://github.com/1Password/op-js
- Owner: 1Password
- License: mit
- Created: 2022-04-14T12:45:44.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-12T02:12:20.000Z (2 months ago)
- Last Synced: 2024-11-06T08:03:37.194Z (7 days ago)
- Language: TypeScript
- Homepage: https://developer.1password.com/docs/cli
- Size: 1.29 MB
- Stars: 94
- Watchers: 9
- Forks: 8
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# op-js
This package is a simple JavaScript wrapper for the [1Password CLI](https://developer.1password.com/docs/cli). It provides methods for most of the CLI's [commands](https://developer.1password.com/docs/cli/reference), and in many cases extends the CLI's ability to authenticate using [biometrics](https://developer.1password.com/docs/cli/about-biometric-unlock) to whatever Node-based application you're building. It also includes TypeScript declarations.
## Installation
Install using Yarn:
```shell
yarn add @1password/op-js
```
Or using NPM:
```shell
npm install @1password/op-js
```
## Usage
After installation you can start using command methods:
```js
import { version, item, connect } from "@1password/op-js";
// Some command functions may be directly imported
version();
// But most exist on their parent command's object
item.get("x1oszeq62e2ys32v9a3l2sgcwly");
// And sub-commands are nested even further
connect.group.revoke({
group: "MyGroup",
allServers: true,
});
```
The CLI takes flags as `kebab-case`, however to align better with JS object convention all flags should be provided as `camelCase`.
### Flags
All command methods support support [global command flags](https://developer.1password.com/docs/cli/reference#global-flags), as well as their own flags, but this package also provides a helper to set global command flags do you don't need to each time. For example:
```js
import { setGlobalFlags } from "@1password/op-js";
setGlobalFlags({
account: "example.1password.com",
});
```
Note that you should not try to set the `--format` flag as this is set under the hood to `json` for all commands that can return JSON format; it is otherwise a string response.
### Validating the CLI
Since this package depends on the 1Password CLI it's up to the user to install it, and the types may depend on a specific version. There is a function that your application can call to validate that the user has the CLI installed at a specific version:
```js
import { validateCli } from "@1password/op-js";
validateCli().catch((error) => {
console.log("CLI is not valid:", error.message);
});
// defaults to the recommended version, but you can supply a semver:
validateCli(">=2.3.1").catch((error) => {
console.log("CLI is not valid:", error.message);
});
```
### Authentication
By default `op-js` uses system authentication (e.g. biometrics), but it also supports automated authentication via [Connect Server](https://developer.1password.com/docs/connect) or [Service Account](https://developer.1password.com/docs/service-accounts).
**Connect**
If you've got a Connect Server set up you can supply your host and token:
```
import { setConnect } from "@1password/op-js";
setConnect("https://connect.myserver.com", "1kjhd9872hd981865s");
```
Alternatively you can use environment variables when executing the code that uses `op-js`:
```
OP_CONNECT_HOST=https://connect.myserver.com
OP_CONNECT_TOKEN=1kjhd9872hd981865s
```
**Service Account**
If you're using service accounts you can supply your token:
```
import { setServiceAccount } from "@1password/op-js";
setServiceAccount("1kjhd9872hd981865s");
```
Alternatively you can use environment variables when executing the code that uses `op-js`:
```
OP_SERVICE_ACCOUNT_TOKEN=1kjhd9872hd981865s
```
### Available commands and functions
There are roughly 70 commands available for use, so you're encouraged to check out the main [`index.ts`](./src/index.ts) file to get a better sense of what's available. Generally, though, here are the top-level commands/namespaces you can import:
- `version` - Retrieve the current version of the CLI
- `inject` - Inject secrets into a config file
- `read` - Read a secret by secret references
- `account` - Manage accounts
- `document` - Manage documents in a vault
- `eventsApi` - Create an Events API integration token
- `connect` - Manage Connect groups, services, tokens, and vaults
- `item` - Manage vault items and templates
- `vault` - Manage account vaults
- `user` - Manage account users
- `group` - Manage groups and their users
- `whoami` - Get details about the authenticated account
## Contributing and feedback
🐛 If you find an issue you'd like to report, or otherwise have feedback, please [file a new Issue](https://github.com/1Password/op-js/issues/new).
🧑💻 If you'd like to contribute to the project please start by filing or commenting on an [Issue](https://github.com/1Password/op-js/issues) so we can track the work. Refer to the [Contributing doc](https://github.com/1Password/op-js/blob/main/CONTRIBUTING.md) for development setup instructions.
💬 Share your feedback and connect with the Developer Products team in the [1Password Developers Slack](https://developer.1password.com/joinslack) workspace.
## License
MIT