@ktmcp-cli/1password 1.0.0

package/AGENT.md

@@ -0,0 +1,48 @@
+# 1Password CLI - AI Agent Guide
+
+This CLI provides programmatic access to the 1Password Secrets/Connect API.
+
+## Quick Start for AI Agents
+
+```bash
+1password config set --token YOUR_CONNECT_TOKEN
+1password config set --base-url https://your-connect-server.example.com
+1password vaults list
+```
+
+## Available Commands
+
+### config
+- `1password config set --token <token>` - Set Connect API token
+- `1password config set --base-url <url>` - Set Connect server URL
+- `1password config get <key>` - Get a config value
+- `1password config list` - List all config values
+
+### vaults
+- `1password vaults list` - List all vaults
+- `1password vaults get <vault-id>` - Get vault details
+
+### items
+- `1password items list <vault-id>` - List items in a vault
+- `1password items list <vault-id> --filter <query>` - Filter items by title
+- `1password items get <vault-id> <item-id>` - Get item details
+- `1password items create <vault-id> --title <title> --category <category>` - Create item
+- `1password items update <vault-id> <item-id> --title <title>` - Update item
+- `1password items delete <vault-id> <item-id>` - Delete item
+
+### files
+- `1password files list <vault-id> <item-id>` - List files on an item
+- `1password files get <vault-id> <item-id> <file-id>` - Get file metadata
+
+## Output Format
+
+All commands output formatted tables by default. Use `--json` flag for machine-readable JSON output.
+
+```bash
+1password vaults list --json
+1password items get <vault-id> <item-id> --json
+```
+
+## Authentication
+
+This CLI uses 1Password Connect API tokens. You need a 1Password Connect server running and a token configured.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KTMCP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+> "Six months ago, everyone was talking about MCPs. And I was like, screw MCPs. Every MCP would be better as a CLI."
+>
+> — [Peter Steinberger](https://twitter.com/steipete), Founder of OpenClaw
+> [Watch on YouTube (~2:39:00)](https://www.youtube.com/@lexfridman) | [Lex Fridman Podcast #491](https://lexfridman.com/peter-steinberger/)
+
+# 1Password CLI
+
+Production-ready CLI for 1Password Secrets/Connect API.
+
+## Installation
+
+```bash
+npm install -g @ktmcp-cli/1password
+```
+
+## Configuration
+
+```bash
+1password config set --token YOUR_CONNECT_TOKEN
+1password config set --base-url https://your-connect-server.example.com
+```
+
+## Usage
+
+### Vaults
+
+```bash
+# List all vaults
+1password vaults list
+
+# Get vault details
+1password vaults get <vault-id>
+```
+
+### Items
+
+```bash
+# List items in a vault
+1password items list <vault-id>
+
+# Filter items by title
+1password items list <vault-id> --filter "database"
+
+# Get a specific item
+1password items get <vault-id> <item-id>
+
+# Create a new item
+1password items create <vault-id> --title "My Login" --category LOGIN \
+  --fields '[{"label":"username","value":"myuser","type":"STRING"},{"label":"password","value":"secret","type":"CONCEALED"}]'
+
+# Update an item
+1password items update <vault-id> <item-id> --title "Updated Title"
+
+# Delete an item
+1password items delete <vault-id> <item-id>
+```
+
+### Files
+
+```bash
+# List files attached to an item
+1password files list <vault-id> <item-id>
+
+# Get file metadata
+1password files get <vault-id> <item-id> <file-id>
+```
+
+### Configuration
+
+```bash
+# Set a config value
+1password config set --token YOUR_TOKEN
+
+# Get a config value
+1password config get token
+
+# List all config
+1password config list
+```
+
+## JSON Output
+
+All commands support `--json` flag for machine-readable output:
+
+```bash
+1password vaults list --json
+1password items get <vault-id> <item-id> --json
+```
+
+## License
+
+MIT

package/bin/1password.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js';

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ktmcp-cli/1password",
+  "version": "1.0.0",
+  "description": "Production-ready CLI for 1Password Secrets/Connect API - Kill The MCP",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "1password": "bin/1password.js"
+  },
+  "keywords": ["1password", "cli", "api", "ktmcp", "secrets", "vault"],
+  "author": "KTMCP",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "axios": "^1.6.7",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "conf": "^12.0.0"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ktmcp-cli/1password.git"
+  },
+  "homepage": "https://killthemcp.com/1password-cli",
+  "bugs": { "url": "https://github.com/ktmcp-cli/1password/issues" }
+}

package/src/api.js

@@ -0,0 +1,142 @@
+import axios from 'axios';
+import { getConfig } from './config.js';
+
+const DEFAULT_BASE_URL = 'https://connect.1password.com';
+
+function getClient() {
+  const token = getConfig('token');
+  const baseURL = getConfig('baseUrl') || DEFAULT_BASE_URL;
+
+  if (!token) {
+    throw new Error('API token not configured. Run: 1password config set --token YOUR_TOKEN');
+  }
+
+  return axios.create({
+    baseURL,
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      'Accept': 'application/json'
+    }
+  });
+}
+
+function handleApiError(error) {
+  if (error.response) {
+    const status = error.response.status;
+    const data = error.response.data;
+    if (status === 401) throw new Error('Authentication failed. Check your Connect token.');
+    if (status === 403) throw new Error('Access forbidden. Check your API permissions.');
+    if (status === 404) throw new Error('Resource not found.');
+    if (status === 429) throw new Error('Rate limit exceeded. Please wait before retrying.');
+    const message = data?.message || data?.detail || JSON.stringify(data);
+    throw new Error(`API Error (${status}): ${message}`);
+  } else if (error.request) {
+    throw new Error('No response from 1Password Connect API. Check your server URL and connection.');
+  } else {
+    throw error;
+  }
+}
+
+// ============================================================
+// VAULTS
+// ============================================================
+
+export async function listVaults() {
+  try {
+    const client = getClient();
+    const response = await client.get('/v1/vaults');
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function getVault(vaultId) {
+  try {
+    const client = getClient();
+    const response = await client.get(`/v1/vaults/${vaultId}`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+// ============================================================
+// ITEMS
+// ============================================================
+
+export async function listItems(vaultId, { filter } = {}) {
+  try {
+    const client = getClient();
+    const params = {};
+    if (filter) params.filter = filter;
+    const response = await client.get(`/v1/vaults/${vaultId}/items`, { params });
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function getItem(vaultId, itemId) {
+  try {
+    const client = getClient();
+    const response = await client.get(`/v1/vaults/${vaultId}/items/${itemId}`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function createItem(vaultId, itemData) {
+  try {
+    const client = getClient();
+    const response = await client.post(`/v1/vaults/${vaultId}/items`, itemData);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function updateItem(vaultId, itemId, itemData) {
+  try {
+    const client = getClient();
+    const response = await client.put(`/v1/vaults/${vaultId}/items/${itemId}`, itemData);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function deleteItem(vaultId, itemId) {
+  try {
+    const client = getClient();
+    await client.delete(`/v1/vaults/${vaultId}/items/${itemId}`);
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+// ============================================================
+// FILES
+// ============================================================
+
+export async function listFiles(vaultId, itemId) {
+  try {
+    const client = getClient();
+    const response = await client.get(`/v1/vaults/${vaultId}/items/${itemId}/files`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}
+
+export async function getFile(vaultId, itemId, fileId) {
+  try {
+    const client = getClient();
+    const response = await client.get(`/v1/vaults/${vaultId}/items/${itemId}/files/${fileId}`);
+    return response.data;
+  } catch (error) {
+    handleApiError(error);
+  }
+}

package/src/config.js

@@ -0,0 +1,19 @@
+import Conf from 'conf';
+
+const config = new Conf({ projectName: '@ktmcp-cli/1password' });
+
+export function getConfig(key) {
+  return config.get(key);
+}
+
+export function setConfig(key, value) {
+  config.set(key, value);
+}
+
+export function isConfigured() {
+  return !!config.get('token');
+}
+
+export function getAllConfig() {
+  return config.store;
+}

package/src/index.js

@@ -0,0 +1,382 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getConfig, setConfig, isConfigured, getAllConfig } from './config.js';
+import {
+  listVaults, getVault,
+  listItems, getItem, createItem, updateItem, deleteItem,
+  listFiles, getFile
+} from './api.js';
+
+const program = new Command();
+
+// ============================================================
+// Helpers
+// ============================================================
+
+function printSuccess(message) {
+  console.log(chalk.green('✓') + ' ' + message);
+}
+
+function printError(message) {
+  console.error(chalk.red('✗') + ' ' + message);
+}
+
+function printTable(data, columns) {
+  if (!data || data.length === 0) {
+    console.log(chalk.yellow('No results found.'));
+    return;
+  }
+  const widths = {};
+  columns.forEach(col => {
+    widths[col.key] = col.label.length;
+    data.forEach(row => {
+      const val = String(col.format ? col.format(row[col.key], row) : (row[col.key] ?? ''));
+      if (val.length > widths[col.key]) widths[col.key] = val.length;
+    });
+    widths[col.key] = Math.min(widths[col.key], 40);
+  });
+  const header = columns.map(col => col.label.padEnd(widths[col.key])).join('  ');
+  console.log(chalk.bold(chalk.cyan(header)));
+  console.log(chalk.dim('─'.repeat(header.length)));
+  data.forEach(row => {
+    const line = columns.map(col => {
+      const val = String(col.format ? col.format(row[col.key], row) : (row[col.key] ?? ''));
+      return val.substring(0, widths[col.key]).padEnd(widths[col.key]);
+    }).join('  ');
+    console.log(line);
+  });
+  console.log(chalk.dim(`\n${data.length} result(s)`));
+}
+
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function withSpinner(message, fn) {
+  const spinner = ora(message).start();
+  try {
+    const result = await fn();
+    spinner.stop();
+    return result;
+  } catch (error) {
+    spinner.stop();
+    throw error;
+  }
+}
+
+function requireAuth() {
+  if (!isConfigured()) {
+    printError('1Password Connect token not configured.');
+    console.log('\nRun the following to configure:');
+    console.log(chalk.cyan('  1password config set --token YOUR_CONNECT_TOKEN'));
+    console.log(chalk.cyan('  1password config set --base-url https://your-connect-server.example.com'));
+    process.exit(1);
+  }
+}
+
+// ============================================================
+// Program metadata
+// ============================================================
+
+program
+  .name('1password')
+  .description(chalk.bold('1Password CLI') + ' - Secrets and vault management from your terminal')
+  .version('1.0.0');
+
+// ============================================================
+// CONFIG
+// ============================================================
+
+const configCmd = program.command('config').description('Manage CLI configuration');
+
+configCmd
+  .command('set')
+  .description('Set configuration values')
+  .option('--token <token>', '1Password Connect API token')
+  .option('--base-url <url>', '1Password Connect server URL', 'https://connect.1password.com')
+  .action((options) => {
+    if (options.token) {
+      setConfig('token', options.token);
+      printSuccess('Connect token set');
+    }
+    if (options.baseUrl) {
+      setConfig('baseUrl', options.baseUrl);
+      printSuccess(`Base URL set to: ${options.baseUrl}`);
+    }
+    if (!options.token && !options.baseUrl) {
+      printError('No options provided. Use --token or --base-url');
+    }
+  });
+
+configCmd
+  .command('get <key>')
+  .description('Get a configuration value')
+  .action((key) => {
+    const value = getConfig(key);
+    if (value === undefined) {
+      printError(`Key "${key}" not found`);
+    } else {
+      console.log(value);
+    }
+  });
+
+configCmd
+  .command('list')
+  .description('List all configuration values')
+  .action(() => {
+    const all = getAllConfig();
+    console.log(chalk.bold('\n1Password CLI Configuration\n'));
+    const token = all.token;
+    const baseUrl = all.baseUrl;
+    console.log('Token:    ', token ? chalk.green('*'.repeat(16) + token.slice(-4)) : chalk.red('not set'));
+    console.log('Base URL: ', baseUrl ? chalk.green(baseUrl) : chalk.yellow('using default: https://connect.1password.com'));
+    console.log('');
+  });
+
+// ============================================================
+// VAULTS
+// ============================================================
+
+const vaultsCmd = program.command('vaults').description('Manage vaults');
+
+vaultsCmd
+  .command('list')
+  .description('List all vaults')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    requireAuth();
+    try {
+      const vaults = await withSpinner('Fetching vaults...', () => listVaults());
+      if (options.json) { printJson(vaults); return; }
+      printTable(vaults, [
+        { key: 'id', label: 'ID', format: (v) => v?.substring(0, 16) + '...' },
+        { key: 'name', label: 'Name' },
+        { key: 'type', label: 'Type' },
+        { key: 'items', label: 'Items' },
+        { key: 'description', label: 'Description' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+vaultsCmd
+  .command('get <vault-id>')
+  .description('Get details of a specific vault')
+  .option('--json', 'Output as JSON')
+  .action(async (vaultId, options) => {
+    requireAuth();
+    try {
+      const vault = await withSpinner('Fetching vault...', () => getVault(vaultId));
+      if (options.json) { printJson(vault); return; }
+      console.log(chalk.bold('\nVault Details\n'));
+      console.log('ID:          ', chalk.cyan(vault.id));
+      console.log('Name:        ', chalk.bold(vault.name));
+      console.log('Type:        ', vault.type || 'N/A');
+      console.log('Items:       ', vault.items || 0);
+      console.log('Description: ', vault.description || 'N/A');
+      console.log('Created:     ', vault.createdAt || 'N/A');
+      console.log('Updated:     ', vault.updatedAt || 'N/A');
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// ITEMS
+// ============================================================
+
+const itemsCmd = program.command('items').description('Manage vault items');
+
+itemsCmd
+  .command('list <vault-id>')
+  .description('List items in a vault')
+  .option('--filter <query>', 'Filter items by title')
+  .option('--json', 'Output as JSON')
+  .action(async (vaultId, options) => {
+    requireAuth();
+    try {
+      const items = await withSpinner('Fetching items...', () =>
+        listItems(vaultId, { filter: options.filter })
+      );
+      if (options.json) { printJson(items); return; }
+      printTable(items, [
+        { key: 'id', label: 'ID', format: (v) => v?.substring(0, 16) + '...' },
+        { key: 'title', label: 'Title' },
+        { key: 'category', label: 'Category' },
+        { key: 'updatedAt', label: 'Updated' },
+        { key: 'createdAt', label: 'Created' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+itemsCmd
+  .command('get <vault-id> <item-id>')
+  .description('Get a specific item from a vault')
+  .option('--json', 'Output as JSON')
+  .action(async (vaultId, itemId, options) => {
+    requireAuth();
+    try {
+      const item = await withSpinner('Fetching item...', () => getItem(vaultId, itemId));
+      if (options.json) { printJson(item); return; }
+      console.log(chalk.bold('\nItem Details\n'));
+      console.log('ID:       ', chalk.cyan(item.id));
+      console.log('Title:    ', chalk.bold(item.title));
+      console.log('Category: ', item.category);
+      console.log('Created:  ', item.createdAt || 'N/A');
+      console.log('Updated:  ', item.updatedAt || 'N/A');
+      if (item.fields && item.fields.length > 0) {
+        console.log(chalk.bold('\nFields:\n'));
+        printTable(item.fields.filter(f => f.value), [
+          { key: 'label', label: 'Label' },
+          { key: 'type', label: 'Type' },
+          { key: 'value', label: 'Value', format: (v, row) => row.type === 'CONCEALED' ? '****' : (v || 'N/A') }
+        ]);
+      }
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+itemsCmd
+  .command('create <vault-id>')
+  .description('Create a new item in a vault')
+  .requiredOption('--title <title>', 'Item title')
+  .requiredOption('--category <category>', 'Item category (LOGIN|PASSWORD|SERVER|DATABASE|CREDIT_CARD|MEMBERSHIP|PASSPORT|OUTDOOR_LICENSE|WIRELESS_ROUTER|BANK_ACCOUNT|DRIVER_LICENSE|IDENTITY|REWARD_PROGRAM|DOCUMENT|EMAIL_ACCOUNT|SOCIAL_SECURITY_NUMBER|MEDICAL_RECORD|SSH_KEY|API_CREDENTIAL)')
+  .option('--fields <json>', 'Item fields as JSON array, e.g. \'[{"label":"username","value":"myuser","type":"STRING"}]\'')
+  .option('--json', 'Output as JSON')
+  .action(async (vaultId, options) => {
+    requireAuth();
+    let fields = [];
+    if (options.fields) {
+      try { fields = JSON.parse(options.fields); } catch {
+        printError('Invalid JSON for --fields'); process.exit(1);
+      }
+    }
+    try {
+      const item = await withSpinner('Creating item...', () =>
+        createItem(vaultId, {
+          vault: { id: vaultId },
+          title: options.title,
+          category: options.category,
+          fields
+        })
+      );
+      if (options.json) { printJson(item); return; }
+      printSuccess(`Item created: ${chalk.bold(item.title)}`);
+      console.log('ID:       ', item.id);
+      console.log('Category: ', item.category);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+itemsCmd
+  .command('update <vault-id> <item-id>')
+  .description('Update an existing item')
+  .option('--title <title>', 'New item title')
+  .option('--fields <json>', 'Updated fields as JSON array')
+  .option('--json', 'Output as JSON')
+  .action(async (vaultId, itemId, options) => {
+    requireAuth();
+    let fields;
+    if (options.fields) {
+      try { fields = JSON.parse(options.fields); } catch {
+        printError('Invalid JSON for --fields'); process.exit(1);
+      }
+    }
+    try {
+      const existing = await withSpinner('Fetching current item...', () => getItem(vaultId, itemId));
+      const updateData = { ...existing };
+      if (options.title) updateData.title = options.title;
+      if (fields) updateData.fields = fields;
+
+      const item = await withSpinner('Updating item...', () => updateItem(vaultId, itemId, updateData));
+      if (options.json) { printJson(item); return; }
+      printSuccess(`Item updated: ${chalk.bold(item.title)}`);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+itemsCmd
+  .command('delete <vault-id> <item-id>')
+  .description('Delete an item from a vault')
+  .action(async (vaultId, itemId) => {
+    requireAuth();
+    try {
+      await withSpinner('Deleting item...', () => deleteItem(vaultId, itemId));
+      printSuccess('Item deleted successfully');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// FILES
+// ============================================================
+
+const filesCmd = program.command('files').description('Manage files attached to items');
+
+filesCmd
+  .command('list <vault-id> <item-id>')
+  .description('List files attached to an item')
+  .option('--json', 'Output as JSON')
+  .action(async (vaultId, itemId, options) => {
+    requireAuth();
+    try {
+      const files = await withSpinner('Fetching files...', () => listFiles(vaultId, itemId));
+      if (options.json) { printJson(files); return; }
+      printTable(files, [
+        { key: 'id', label: 'ID', format: (v) => v?.substring(0, 16) + '...' },
+        { key: 'name', label: 'Name' },
+        { key: 'size', label: 'Size', format: (v) => v ? `${(v / 1024).toFixed(1)} KB` : 'N/A' },
+        { key: 'content_path', label: 'Content Path' }
+      ]);
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+filesCmd
+  .command('get <vault-id> <item-id> <file-id>')
+  .description('Get file metadata')
+  .option('--json', 'Output as JSON')
+  .action(async (vaultId, itemId, fileId, options) => {
+    requireAuth();
+    try {
+      const file = await withSpinner('Fetching file...', () => getFile(vaultId, itemId, fileId));
+      if (options.json) { printJson(file); return; }
+      console.log(chalk.bold('\nFile Details\n'));
+      console.log('ID:           ', chalk.cyan(file.id));
+      console.log('Name:         ', chalk.bold(file.name));
+      console.log('Size:         ', file.size ? `${(file.size / 1024).toFixed(1)} KB` : 'N/A');
+      console.log('Content Path: ', file.content_path || 'N/A');
+      console.log('');
+    } catch (error) {
+      printError(error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================
+// Parse
+// ============================================================
+
+program.parse(process.argv);
+
+if (process.argv.length <= 2) {
+  program.help();
+}