Skip to content
This repository was archived by the owner on Feb 15, 2026. It is now read-only.

docs: rewrite CLI README #9

Merged
NicolasRitouet merged 4 commits into from
Feb 7, 2026
Merged

docs: rewrite CLI README #9

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a1c82ee
docs: rewrite README with GitHub-native hero, AI/MCP section, streaml…
NicolasRitouet Feb 6, 2026
e3efb65
docs: promote keyway run over keyway pull as default flow
NicolasRitouet Feb 6, 2026
25b7130
docs: clarify GitHub Copilot partial MCP support
NicolasRitouet Feb 6, 2026
1496795
docs: fix code block language and correct MCP tools count
NicolasRitouet Feb 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 90 additions & 57 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Keyway CLI

**Stop sharing `.env` files on Slack.** GitHub access = secret access.
**GitHub-native secrets management.** Repo access = secret access.

[![Release](https://img.shields.io/github/v/release/keywaysh/cli?label=release&color=34D399)](https://github.com/keywaysh/cli/releases/latest)
[![CI](https://github.com/keywaysh/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/keywaysh/cli/actions/workflows/ci.yml)
Expand All @@ -9,73 +9,66 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Keyway Secrets](https://www.keyway.sh/badge.svg?repo=keywaysh/cli)](https://www.keyway.sh/vaults/keywaysh/cli)

---

## The Problem

You're still doing this:
- Pasting secrets in Slack DMs
- Emailing `.env` files to new devs
- Rotating every secret when someone leaves
- Manually copying vars to Vercel/Railway/Netlify
<!-- TODO: replace with a 15s GIF of `keyway init` → `keyway run` -->

## The Solution

```bash
keyway pull
```text
You Teammate
───────────────── ─────────────────
$ keyway init $ keyway run -- npm start
✓ Logged in via GitHub ✓ Logged in via GitHub
✓ Vault created ✓ Injected 12 secrets
✓ Pushed 12 secrets ✓ Server running
Ready. Ready. No .env on disk.
```

That's it. If you have access to the repo, you have access to the secrets. No invites, no training, no friction.

---

## Install

### Homebrew (macOS & Linux)
## Quick Start

```bash
brew install keywaysh/tap/keyway
```

### Install Script
<details>
<summary>Other install methods</summary>

```bash
# Install script (macOS & Linux)
curl -fsSL https://keyway.sh/install.sh | sh
```

### npx (no install)

```bash
# npx (no install)
npx @keywaysh/cli init

# Direct download
# Grab the binary for your platform from Releases:
# https://github.com/keywaysh/cli/releases/latest
```

### Direct download
</details>

Grab the binary for your platform from [Releases](https://github.com/keywaysh/cli/releases/latest).

---

## Quick Start
Then, from your repo:

```bash
keyway init
keyway init # Create vault, push secrets
keyway run -- npm start # Run with secrets injected, nothing on disk
```

This will:
1. Authenticate with GitHub
2. Create an encrypted vault for your repo
3. Push your local `.env` to the vault
A teammate clones the repo and runs:

New teammate joins? They run `keyway pull`. Done in 30 seconds.
```bash
keyway run -- npm start # Secrets injected — 30 seconds from install to running
```

---

## How It Works

```bash
keyway init # First time: create vault, push secrets
keyway run # Run with secrets injected (nothing on disk)
keyway push # Update remote secrets
keyway pull # Get latest secrets
keyway pull # Download secrets as .env (when you need the file)
keyway diff # Compare local vs remote before pushing
keyway sync vercel # Deploy to Vercel, Railway, Netlify
```

Expand All @@ -92,20 +85,55 @@ Secrets exist only in memory. When the process exits, they're gone.

---

## Works with AI Assistants

AI coding agents can read your `.env` files. Keyway keeps secrets out of AI context.

### `keyway run` — secrets never touch disk

The AI sees command output but never secret values:

```bash
keyway run -- npm test # AI sees "tests passed", not your DB password
keyway run -- npm run dev # Secrets in RAM only, invisible to agents
```

### MCP Server — AI manages secrets without seeing them

5 tools your AI assistant can use — `keyway_list_secrets`, `keyway_get_secret`, `keyway_set_secret`, `keyway_inject_run`, and `keyway_list_environments` — with values always masked:

```bash
# Claude Code
claude mcp add keyway -- npx @keywaysh/mcp

# VS Code / Cursor
code --add-mcp '{"name":"keyway","command":"npx","args":["@keywaysh/mcp"]}'
```

Works with Claude Code, VS Code, Cursor, Windsurf, Warp, GitHub Copilot*, and Goose.

*GitHub Copilot supports MCP tools only (not resources or prompts).

[MCP Server docs →](https://github.com/keywaysh/keyway-mcp) · [AI agents guide →](https://docs.keyway.sh/ai-agents)

---

## Security

Your secrets are protected by:

| Layer | Protection |
|-------|------------|
| **Encryption** | AES-256-GCM with random IV per secret |
| **At Rest** | Encrypted in database, keys in isolated service |
| **At Rest** | Encrypted in database, keys in isolated Go crypto microservice |
| **In Transit** | TLS 1.3 everywhere |
| **Access Control** | GitHub collaborator API — no separate user management |
| **Audit Trail** | Every pull and view is logged with IP and location |

We can't read your secrets. Even if our database leaks, attackers get encrypted blobs.

Self-hostable — run the entire stack on your own infrastructure with Docker Compose.

[Read our security whitepaper →](https://www.keyway.sh/security)
Comment on lines +135 to 137
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check for Docker Compose files
echo "=== Looking for Docker Compose files ==="
fd -t f -e yml -e yaml | grep -i compose

echo ""
echo "=== Searching for docker-compose specific files ==="
fd -type f "docker-compose" 

echo ""
echo "=== Checking for self-hosting and Docker Compose references in markdown ==="
rg -i "self.?host|docker.?compose" --type md -B 2 -A 2

echo ""
echo "=== Checking for security/whitepaper references ==="
rg -i "security" --type md -B 1 -A 1 | head -50

Repository: keywaysh/cli

Length of output: 1619

🌐 Web query:

keyway.sh security whitepaper

💡 Result:

I couldn’t find a standalone “security whitepaper” published under keyway.sh. Instead, Keyway documents its security model in these official pages:

  • Keyway Security (website): architecture overview and claims such as an isolated (no-internet) crypto service, AES-256-GCM encryption, TLS 1.3, GitHub-native access control, audit trail, and open-source core. [1]
  • Keyway Docs → Security: operational security features like activity logs, security alerts, and vulnerability reporting. [2]
  • Keyway Docs → Getting Started (“How it works” diagram): high-level system diagram showing the isolated crypto service alongside the API and database. [3]

Sources:
[1] https://www.keyway.sh/security
[2] https://docs.keyway.sh/security
[3] https://docs.keyway.sh/

🌐 Web query:

keyway.sh docker compose self-hosting

💡 Result:

I couldn’t find any official Docker Compose self-hosting instructions for Keyway (keyway.sh). The published docs describe a hosted Keyway API (base URL https://api.keyway.sh/v1) that the CLI talks to, not a self-hostable server distribution or docker-compose.yml. [1], [2]. Their security page also describes their infrastructure as hosted (on Railway, EU), which further suggests it’s a SaaS offering rather than something you run yourself. [3]

If you actually meant Keygen (keygen.sh) (very similar name), that project has an official Docker Compose self-hosting guide, including running a setup profile and then docker compose up. [4]

Sources: [1] [2] [3] [4]

Remove or correct the misleading self-hosting claim in line 135.

The claim "Self-hostable — run the entire stack on your own infrastructure with Docker Compose" is not supported. No Docker Compose files exist in the repository, the README contains a <!-- TODO: add self-hosting guide link when docs page is live --> comment indicating documentation is missing, and the actual service operates as a hosted SaaS API. This claim is contradicted by your own service model (hosted on Railway, EU with a remote https://api.keyway.sh/v1 endpoint). Either add genuine self-hosting support with documented Docker Compose files and guides, or remove this claim to avoid misleading users.

Regarding the "security whitepaper" link on line 137: The referenced page (https://www.keyway.sh/security) exists but contains a security overview/claims summary rather than a formal whitepaper. Consider retitling the link accordingly if accuracy is important.

🤖 Prompt for AI Agents 
In `@README.md` around lines 135 - 137, The README contains an unsupported
self-hosting claim "Self-hostable — run the entire stack on your own
infrastructure with Docker Compose" which is misleading; either remove that
sentence or replace it with an accurate statement (e.g., "Hosted SaaS —
currently available via https://api.keyway.sh; self-hosting guide and Docker
Compose are not provided") and, if you intend to support self-hosting, add the
actual Docker Compose files and a documented guide and update the README to
reference them; also update the "security whitepaper" link text to a more
accurate label like "Security overview" if the linked page is not a formal
whitepaper.


---
Expand All @@ -131,25 +159,6 @@ We can't read your secrets. Even if our database leaks, attackers get encrypted

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `KEYWAY_TOKEN` | Auth token for CI/CD (create in Dashboard > API Keys) |
| `KEYWAY_API_URL` | Custom API endpoint |
| `KEYWAY_DISABLE_TELEMETRY=1` | Disable anonymous analytics |

---

## Why Keyway?

- **30 seconds** to onboard a new developer
- **0 secrets** to rotate when someone leaves (just revoke GitHub access)
- **1 command** to deploy secrets to production
- **GitHub-native** — no new accounts, no new permissions to manage

---

## CI/CD

Use an API key for automation:
Expand Down Expand Up @@ -177,6 +186,27 @@ Or use the [GitHub Action](https://github.com/keywaysh/keyway-action):

---

## Why Keyway?

- **30 seconds** to onboard a new developer
- **0 secrets** to rotate when someone leaves (just revoke GitHub access)
- **1 command** to deploy secrets to production
- **GitHub-native** — no new accounts, no new permissions to manage
- **First-class AI support** — MCP server and zero-trust mode keep secrets out of AI context
- **Fully open-source** — MIT licensed, self-hostable, auditable

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `KEYWAY_TOKEN` | Auth token for CI/CD (create in Dashboard > API Keys) |
| `KEYWAY_API_URL` | Custom API endpoint |
| `KEYWAY_DISABLE_TELEMETRY=1` | Disable anonymous analytics |

---

## Development

```bash
Expand All @@ -197,6 +227,9 @@ Releases are automated via GoReleaser on tag push.
- [Documentation](https://docs.keyway.sh)
- [Dashboard](https://keyway.sh)
- [Security](https://keyway.sh/security)
- [MCP Server](https://github.com/keywaysh/keyway-mcp)
- [GitHub Action](https://github.com/keywaysh/keyway-action)
<!-- TODO: add self-hosting guide link when docs page is live -->
- [Status](https://status.keyway.sh)

---
Expand Down
Loading