Skip to content

README.md

Latest commit

 

History

History
157 lines (110 loc) · 4.18 KB

README.md

File metadata and controls

157 lines (110 loc) · 4.18 KB

swift-pass

swift-pass is a macOS command-line tool for storing and retrieving secrets from Apple's Keychain with a simple, scope-aware CLI.

It supports a default group, named groups, and one level of subgroup nesting so you can organize credentials by project and environment without leaving the terminal.

Features

  • Store, read, list, and delete secrets from the macOS Keychain
  • Organize secrets by default group, named group, or subgroup scope
  • Create groups and subgroups explicitly with create
  • Browse secrets and groups with plain-text or interactive Noora-powered output
  • Run doctor to inspect signing, Keychain access, catalog health, and orphaned entries
  • Bootstrap the default catalog automatically on first write
  • Migrate legacy flat secrets into the default group during bootstrap

Installation

swift-pass is currently built from source with Xcode at the repository root.

Requirements

  • macOS
  • Xcode with command line tools installed

Build From Source

  1. Clone the repository.
  2. List available schemes if needed:
xcodebuild -list -project "swift-pass.xcodeproj"
  1. Build the debug executable:
xcodebuild -project "swift-pass.xcodeproj" -scheme "swift-pass" -configuration Debug -derivedDataPath Build build
  1. Run the built binary:
"Build/Products/Debug/swift-pass" --help

Usage

Secret Scopes

  • Default group: name
  • Named group: group:name
  • Subgroup: group:subgroup:name

Common Commands

Store secrets:

"Build/Products/Debug/swift-pass" set "github=token"
"Build/Products/Debug/swift-pass" set "myproject:github=token"
"Build/Products/Debug/swift-pass" set "myproject:dev:github=token"

Read and delete secrets:

"Build/Products/Debug/swift-pass" get "myproject:dev:github"
"Build/Products/Debug/swift-pass" delete "myproject:dev:github"

Create scopes:

"Build/Products/Debug/swift-pass" create "myproject"
"Build/Products/Debug/swift-pass" create "myproject:dev"

List secrets:

"Build/Products/Debug/swift-pass" list
"Build/Products/Debug/swift-pass" list --group myproject --subgroup dev
"Build/Products/Debug/swift-pass" list --plain
"Build/Products/Debug/swift-pass" list --interactive

List groups and subgroups:

"Build/Products/Debug/swift-pass" groups
"Build/Products/Debug/swift-pass" groups myproject
"Build/Products/Debug/swift-pass" gs --plain
"Build/Products/Debug/swift-pass" groups --interactive

Run diagnostics:

"Build/Products/Debug/swift-pass" doctor

Tech Stack

  • Swift
  • Xcode project-based build setup
  • swift-argument-parser for command parsing
  • Noora for prompts, tables, and terminal UX
  • Valet plus the macOS Security framework for Keychain access
  • XCTest for automated tests

Project Structure

swift-pass/
  Commands/    CLI subcommands and argument resolution
  Keychain/    Keychain access, scope catalog, signing checks, and vault logic
  Support/     Shared prompting helpers
  main.swift   CLI entry point
swift-passTests/  XCTest coverage for parsing, listing, groups, and vault behavior
swift-pass.xcodeproj/  Xcode project and package wiring
Build/  Local derived build output

Development

Build the project:

xcodebuild -project "swift-pass.xcodeproj" -scheme "swift-pass" -configuration Debug -derivedDataPath Build build

Run the full test suite:

xcodebuild -project "swift-pass.xcodeproj" -scheme "swift-pass" -configuration Debug -derivedDataPath Build test

Run a single test class:

xcodebuild -project "swift-pass.xcodeproj" -scheme "swift-pass" -configuration Debug -derivedDataPath Build test -only-testing:"swift-passTests/SecretVaultTests"

Contributing

Contributions are welcome.

  1. Fork the repository and create a focused branch.
  2. Follow the existing Swift style and keep changes narrowly scoped.
  3. Add or update tests when behavior changes.
  4. Verify your work with xcodebuild before opening a pull request.
  5. Update docs when commands, workflows, or project structure change.

License

No license file is currently present in this repository.