This package is a simple JavaScript wrapper for the 1Password CLI. It provides methods for most of the CLI's commands, and in many cases extends the CLI's ability to authenticate using biometrics to whatever Node-based application you're building. It also includes TypeScript declarations.
Install using Yarn:
yarn add @1password/op-jsOr using NPM:
npm install @1password/op-jsAfter installation you can start using command methods:
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.
All command methods support support global command 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:
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.
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:
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);
});By default op-js uses system authentication (e.g. biometrics), but it also supports automated authentication via Connect Server or Service Account.
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
There are roughly 70 commands available for use, so you're encouraged to check out the main 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 CLIinject- Inject secrets into a config fileread- Read a secret by secret referencesaccount- Manage accountsdocument- Manage documents in a vaulteventsApi- Create an Events API integration tokenconnect- Manage Connect groups, services, tokens, and vaultsitem- Manage vault items and templatesvault- Manage account vaultsuser- Manage account usersgroup- Manage groups and their userswhoami- Get details about the authenticated account
🐛 If you find an issue you'd like to report, or otherwise have feedback, please file a new Issue.
🧑💻 If you'd like to contribute to the project please start by filing or commenting on an Issue so we can track the work. Refer to the Contributing doc for development setup instructions.
💬 Share your feedback and connect with the Developer Products team in the 1Password Developers Slack workspace.
MIT