1Password Client Library

A unified TypeScript client library for accessing 1Password via either:

• 1Password Connect (self-hosted)
• 1Password Cloud SDK

This package provides a single, consistent API regardless of which backend you're using.

Installation

npm install @teamsparkai/1password

Library Usage

Basic Example

import { createOnePasswordClient } from '@teamsparkai/1password';

// Create a client (automatically detects Connect vs Cloud based on options)
const client = await createOnePasswordClient({
  serviceAccountToken: process.env.OP_SERVICE_ACCOUNT_TOKEN
  // OR
  // connectToken: process.env.OP_CONNECT_TOKEN,
  // connectHost: process.env.OP_CONNECT_HOST || 'http://localhost:8080'
});

// List all vaults
const vaults = await client.listVaults();

// Find a vault by name or ID
const vault = await client.findVault('My Vault');

// List items in a vault
const items = await client.listItems(vault.id);

// Find an item
const item = await client.findItem(vault.id, 'My Item');

Parse op:// URIs

import { parseOpUri } from '@teamsparkai/1password';

const parsed = parseOpUri('op://vault-name/item-name/password');
// Returns: { vault: 'vault-name', item: 'item-name', field: 'password' }

CLI Demo

This package includes a CLI tool that demonstrates how to use the library. It's a fully functional interactive CLI for browsing your 1Password vaults.

Installation

npm install -g @teamsparkai/1password

Usage

# Start the interactive CLI
1password

# Or run from project directory
npm start

Configuration

Create a .env file in your working directory (or set environment variables):

For 1Password Connect:

OP_CONNECT_TOKEN=your_connect_token
OP_CONNECT_HOST=http://localhost:8080  # Optional, defaults to localhost:8080

For 1Password Cloud:

OP_SERVICE_ACCOUNT_TOKEN=your_service_account_token

CLI Commands

• /vaults - List all accessible vaults
• /vault <vaultName|vaultId> - List items in a specific vault
• /item <vaultName|vaultId> <itemName|itemId> [-s|--show] - Show item details
• /read <op://uri> [-s|--show] - Read item from op:// URI
• /info - Show connection information
• /help - Show help menu
• /quit or /exit - Exit the application

API Reference

createOnePasswordClient(options)

Creates a 1Password client instance.

Options:

• connectToken?: string - Token for 1Password Connect
• connectHost?: string - Host URL for Connect (defaults to http://localhost:8080)
• serviceAccountToken?: string - Service account token for Cloud SDK

Returns: Promise<OnePasswordClient>

OnePasswordClient

Interface for interacting with 1Password.

Properties:

• type: 'connect' | 'cloud' - The client type
• description: string - Human-readable connection description

Methods:

• listVaults(): Promise<VaultInfo[]> - List all accessible vaults
• findVault(vaultQuery: string): Promise<VaultInfo | null> - Find vault by name or ID
• listItems(vaultId: string): Promise<ItemInfo[]> - List items in a vault
• findItem(vaultQuery: string, itemQuery: string): Promise<ItemDetail | null> - Find item by vault and item name/ID

Types

All types are exported from the main package:

import type {
  OnePasswordClient,
  VaultInfo,
  ItemInfo,
  ItemDetail,
  ItemFieldInfo,
  ItemSectionInfo,
  ItemUrlInfo
} from '@teamsparkai/1password';

Architecture

The library uses an adapter pattern to provide a unified interface:

• OnePasswordClient - Unified interface
• OnePasswordConnectClient - Implementation for Connect (self-hosted)
• OnePasswordCloudClient - Implementation for Cloud SDK

Both implementations convert their native data formats to a canonical format based on the Cloud SDK's types, ensuring consistency across backends.

License

MIT