OnePassword.NET - 1Password CLI Wrapper

This library serves as a .NET wrapper for the 1Password command-line tool op ( Download | Documentation ).

References

This library targets .NET Standard 2.1.

Dependencies

This library has no dependencies.

Breaking changes for 2.5.0

• ShareItem(...) now returns ItemShare instead of void.

Quick start

Creating an instance of the manager

varonePassword=newOnePasswordManager();

The default executable name is op.exe on Windows and op on other platforms. If the CLI isn't in the current working directory, set options.Path and, if needed, options.Executable.

Adding your account and signing in for the first time

vardomain="my.1password.com";varemail="your@email.com";varsecretKey="A3-YOUR-SECRET-KEY";varpassword="yourpassword";onePassword.AddAccount(domain,email,secretKey,password);onePassword.SignIn(password);

Signing in for subsequent connections

onePassword.UseAccount(domain);onePassword.SignIn(password);

Using Service Accounts

To signin using a Service Account, a token must be provided as part of the options.

varonePassword=newOnePasswordManager(options =>{options.ServiceAccountToken="yourtoken";});

Subsequently, the following commands are not used or supported when using service accounts.

• GetAccounts, GetAccount, AddAccount, UseAccount, ForgetAccount
• SignIn, SignOut

For more information, see the documentation on 1Password Service Accounts.

Getting all vaults

varvaults=onePassword.GetVaults();

Selecting a specific vault

varvault=vaults.First(x =>x.Name=="Private");

Creating an item using a template

varserverTemplate=onePassword.GetTemplate(Category.Server);serverTemplate.Title="Your Item's Title";serverTemplate.Fields.First(x =>x.Label=="username").Value="secretuser";serverTemplate.Fields.First(x =>x.Label=="password").Value="secretpass";varserverItem=onePassword.CreateItem(serverTemplate,vault);

Note: If you want to reuse the same template for several items, make sure you clone the instance to avoid reference issues.

varserver1=serverTemplate.Clone();varserver2=serverTemplate.Clone();

Getting all items in a vault

GetItems(...) returns summary items. Fetch the item details with GetItem(...) before relying on Fields, Sections, or other hydrated properties.

varitems=onePassword.GetItems(vault);

Selecting a specific item

varitemSummary=items.First(x =>x.Title=="Your Item's Title");varitem=onePassword.GetItem(itemSummary,vault);

Editing a specific item

item.Fields.First(x =>x.Label=="password").Value="newpass";onePassword.EditItem(item,vault);

Adding a field to an existing item

varitemToExtend=onePassword.GetItem(itemSummary,vault);itemToExtend.Fields.Add(newField("Environment",FieldType.String,"Production"));onePassword.EditItem(itemToExtend,vault);

The same hydrate-edit-save flow applies to items based on custom templates. Fetch the hydrated item with GetItem(...) before editing so the wrapper preserves the item's template-backed category_id in the edit payload.

Adding file attachments to an item

varitemToAttach=onePassword.GetItem(itemSummary,vault);itemToAttach.FileAttachments.Add(newFileAttachment(@"C:\Files\Production.env","Production Env"));onePassword.EditItem(itemToAttach,vault);

Removing a file attachment from an item

varitemToUpdate=onePassword.GetItem(itemSummary,vault);varattachment=itemToUpdate.FileAttachments.First(x =>x.Name=="Production Env");itemToUpdate.FileAttachments.Remove(attachment);onePassword.EditItem(itemToUpdate,vault);

Reading file attachment metadata and content

FileAttachments are hydrated by GetItem(...) and expose attachment metadata returned by the CLI. Use SaveFileAttachmentContent(...) to download the attachment content, or GetFileAttachmentReference(...) when you need the secret reference built from the vault, item, and attachment IDs.

varitemWithAttachments=onePassword.GetItem(itemSummary,vault);varattachment=itemWithAttachments.FileAttachments.First();onePassword.SaveFileAttachmentContent(attachment,itemWithAttachments,vault,@"C:\Files\Production.env");

Sharing an item without email restrictions

varshare=onePassword.ShareItem(item,vault);Console.WriteLine(share.Url);

Sharing an item with email restrictions

varshare=onePassword.ShareItem(item,vault,"recipient@example.com",expiresIn:TimeSpan.FromDays(7),viewOnce:true);Console.WriteLine(share.Url);

Sharing an item with multiple email restrictions

varshare=onePassword.ShareItem(item,vault,new[]{"recipient1@example.com","recipient2@example.com"});Console.WriteLine(share.Url);

Archiving an item

onePassword.ArchiveItem(item,vault);

Deleting an item

onePassword.DeleteItem(item,vault);

Signing out

onePassword.SignOut();

Running tests

Due to the fact that this library acts as a wrapper for the CLI and in order for tests to have any significant value, the majority of tests are integration tests which must run against an active 1Password account (preferably a Business account).

The live test harness is pinned to and was last verified against 1Password CLI 2.32.1.

Effects on the active account

The integration tests will sign in to the specified account, then create and update a test group, a test user (optional), and a test vault. Items will then be created and update in the test vault. Finally, the test vault, user, and group will be deleted. Note: If the integration tests fail, test data may remain in the specified account.

Configuration

The integration tests are configured using the environment variables which are prefixed with OPT_ (OnePassword Tests). Environment variables which are integers must contain only numbers and those which are booleans must contain true or false as a string.

Environment Variable	Description	Type	Default Value
OPT_COMMAND_TIMEOUT	The timeout (in minutes) for each CLI command.	int	2
OPT_RATE_LIMIT	The rate (in milliseconds) at which commands are executed.	int	250
OPT_RUN_LIVE_TESTS	Activates or deactivates integration tests.	bool	false
OPT_CREATE_TEST_USER	Activates or deactivates the creation of the test user and its related tests.	bool	false
OPT_ACCOUNT_ADDRESS	The account address. Should be the host name only.	string
OPT_ACCOUNT_EMAIL	The email to use when authenticating.	string
OPT_ACCOUNT_NAME	The account name. Used to test account related commands.	string
OPT_ACCOUNT_PASSWORD	The password to use when authenticating.	string
OPT_ACCOUNT_SECRET_KEY	The secret key to use when authenticating.	string
OPT_TEST_USER_EMAIL	The test user's email address.	string
OPT_TEST_USER_CONFIRM_TIMEOUT	The time (in minutes) to wait for manual confirmation of the test user.	int	OPT_COMMAND_TIMEOUT

Disclaimer

While the use of the 1Password name and logo is authorized, it's important to note that this library is not an official product developed or maintained by AgileBits, Inc.