Headless Vault CLI

Access Markdown notes on your personal computer from this VPS-hosted bot via SSH tunnel.

Terminology: "Local machine" = your personal computer (macOS or Linux) where your notes live. This skill runs on the VPS and connects to your machine via a reverse SSH tunnel.

Prerequisites

This is an instruction-only skill. Before using it, the user must complete a one-time setup on their local machine:

1. 1. Install vaultctl on the local machine (see setup instructions)
2. Configure SSH forced-command on the local machine's ~/.ssh/authorized_keys to restrict the VPS key to only run vaultctl (see Security Model below)
3. Start a reverse SSH tunnel from the local machine to the VPS, exposing INLINECODE2
4. Set the environment variable VAULT_SSH_USER to the local machine's username

Security Model

This skill connects to the local machine over a pre-configured reverse SSH tunnel. Access is restricted by design:

• - Forced-command restriction: The VPS SSH key is added to the local machine's ~/.ssh/authorized_keys with a forced-command wrapper, so the VPS can ONLY execute vaultctl — no interactive shell, no arbitrary commands (rm, curl, etc.)
• Vault sandboxing: vaultctl validates all file paths are inside VAULT_ROOT and rejects path traversal attempts (.., symlinks outside vault)
• Non-destructive: Only create (new files) and append (existing files) are supported — no delete, rename, move, or overwrite
• No credentials stored: SSH authentication uses the VPS's existing SSH keypair; no additional secrets are stored by this skill

Example authorized_keys entry on the local machine:
CODEBLOCK0

This ensures the VPS can only run vaultctl commands, even if the tunnel is compromised.

Available Commands

You have access to these commands ONLY. Do not attempt commands not listed here (no rename, delete, move, or edit commands exist).

How to Run Commands

All commands are executed via SSH:
CODEBLOCK1

Always use -4 to force IPv4 (avoids IPv6 timeout issues).

Environment Variables

These must be set in the skill's runtime environment on the VPS:

Command Reference

tree - List vault structure

ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl tree
ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl tree --depth 2
ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl tree --all

• - --depth N - Maximum depth to traverse
• INLINECODE28 - Include all files, not just .md

resolve - Find note by path or title

ALWAYS use --base64 for path and title arguments to prevent shell injection:
CODEBLOCK3

info - Get file metadata

ALWAYS use --base64 for the path argument:

# echo -n "Projects/Plan.md" | base64 → UHJvamVjdHMvUGxhbi5tZA==
ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl info UHJvamVjdHMvUGxhbi5tZA== --base64

read - Read note content

ALWAYS use --base64 for the path argument:

# echo -n "Projects/Plan.md" | base64 → UHJvamVjdHMvUGxhbi5tZA==
ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl read UHJvamVjdHMvUGxhbi5tZA== --base64

create - Create a NEW note

CODEBLOCK6

Example to create "Notes/Morning Brief.md" with content "# Hello\n\nWorld":
CODEBLOCK7

• - Creates parent directories automatically
• Fails if file already exists (use append to add to existing files)
• File must have .md extension
• NEVER duplicate the title as a heading inside the note content (e.g., for "My Note.md", don't start content with "# My Note")

append - Append to EXISTING note

• - Fails if file does not exist (use create for new files)

What You CANNOT Do

These operations are NOT supported:

• - Rename files or folders
• Delete files or folders
• Move files between folders
• Edit specific parts of a file (only append to end)
• Create folders without a file (folders are created automatically with create)

Tips

• - Always run vaultctl tree first to see what notes exist
• Use vaultctl resolve --title <base64> --base64 to find a note by name
• All output is JSON
• The local machine must be online with tunnel running
• ALWAYS use --base64 for ALL path and content arguments — this is mandatory for security, not optional

Examples

Important: Always run tree first if you're unsure what notes exist. This prevents errors from wrong paths or duplicate names.

Example 1: User asks to read a note (check first)

Step 1 - Check what exists:

ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl tree

Step 2 - Now read the correct path (always base64 encode):

# echo -n "Projects/Plan.md" | base64 → UHJvamVjdHMvUGxhbi5tZA==
ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl read UHJvamVjdHMvUGxhbi5tZA== --base64

Example 2: User asks to create a note (check first to avoid duplicates)

Step 1 - Check what already exists:

ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl tree

Step 2 - No "Meeting Notes" exists, safe to create (do NOT duplicate title as heading):

# echo -n "Meeting Notes.md" | base64 → TWVldGluZyBOb3Rlcy5tZA==
# echo -n "## Agenda\n\n- Item 1\n- Item 2\n" | base64 → IyMgQWdlbmRhCgotIEl0ZW0gMQotIEl0ZW0gMgo=
ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl create TWVldGluZyBOb3Rlcy5tZA== IyMgQWdlbmRhCgotIEl0ZW0gMQotIEl0ZW0gMgo= --base64

Example 3: User asks about vault contents

CODEBLOCK17
Output:
CODEBLOCK18

Then summarize for user: "You have a Projects folder with Plan.md, and an Ideas.md file at the root."

Example 4: Complex workflow with source and output notes

Step 1 - Check what exists:

ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl tree

Step 2 - Validate:

• - Source "AI Digest Sources.md" exists
• Output "digest/2025-01-28-digest.md" does NOT exist, will use INLINECODE43

(If source didn't exist: STOP and ask user "I couldn't find 'AI Digest Sources.md'. Did you mean one of these: [list alternatives]?")

(If output already existed: use append instead of create)

Step 3 - Read the source note (always base64 encode):

# echo -n "AI Digest Sources.md" | base64 → QUkgRGlnZXN0IFNvdXJjZXMubWQ=
ssh -4 -p 2222 ${VAULT_SSH_USER}@localhost vaultctl read QUkgRGlnZXN0IFNvdXJjZXMubWQ= --base64

Step 4 - Browse sources and generate digest content (done by bot outside this skill)

Step 5 - Write output to vault (do NOT duplicate title as heading):
CODEBLOCK23

(If output already existed, use append instead:)
CODEBLOCK24