VS Code Extension

Browse, peek, and manage secrets from your Arcan server directly in VS Code.

Installation

Install from the VS Code Marketplace:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Arcan Secrets"
4. Click Install

Or install from a .vsix file:

code --install-extension arcan-secrets-0.1.0.vsix

Configuration

Run Arcan: Configure Connection from the command palette (Ctrl+Shift+P / Cmd+Shift+P) to set up your connection.

Setting	Default	Description
arcan.serverUrl	https://localhost:8443	Arcan server URL
arcan.token	(empty)	API token (prefer SecretStorage via Configure command)
arcan.defaultRealm	default	Default realm slug
arcan.defaultEnv	dev	Default environment
arcan.rejectUnauthorized	true	Reject invalid TLS certificates (set to false for self-signed)

The API token can also be set via the ARCAN_TOKEN environment variable.

Features

Sidebar Tree View

Browse secrets organized by realm and environment in the Arcan sidebar panel. Secret values are never shown in the tree view -- only key names are displayed.

Hover to Preview

Hover over environment variable references in your code to see the corresponding Arcan value.

Supported languages:

Language	Pattern
JavaScript/TypeScript	process.env.KEY
Python	os.environ["KEY"], os.getenv("KEY")
Go	os.Getenv("KEY")
Shell	$KEY, ${KEY}
.env files	KEY=value

Peek Secret Values

View secret values in a notification without opening files. Values are shown masked (first 2 and last 2 characters only).

Copy to Clipboard

Copy secret values with automatic 30-second clipboard clearing for security.

Insert References

Insert language-appropriate environment variable references from a quick-pick menu.

Set/Update Secrets

Create or update secrets directly from the command palette.

Commands

Command	Description
Arcan: Refresh Secrets	Refresh the secrets tree and clear hover cache
Arcan: Copy Secret Value	Copy a secret value to clipboard (auto-clears after 30s)
Arcan: Peek Secret Value	Show a secret value in a notification
Arcan: Set Secret	Create or update a secret
Arcan: Delete Secret	Delete a secret (with confirmation)
Arcan: Insert Secret Reference	Insert a language-appropriate env var reference
Arcan: Configure Connection	Set API token or open settings

Keyboard Shortcuts

Open the command palette with Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) and type "Arcan:" to see all available commands.

Shortcut	Command	What it does
Cmd+Shift+P → "Arcan: Refresh"	arcan.refresh	Reload all secrets from the server and clear the hover cache
Cmd+Shift+P → "Arcan: Peek"	arcan.peek	Show a masked preview of a secret in a notification
Cmd+Shift+P → "Arcan: Copy"	arcan.copy	Copy a secret value to clipboard (auto-clears in 30s)
Cmd+Shift+P → "Arcan: Set"	arcan.set	Create or update a secret via input prompts
Cmd+Shift+P → "Arcan: Insert"	arcan.insert	Insert a language-appropriate env var reference at cursor
Cmd+Shift+P → "Arcan: Configure"	arcan.configure	Set your server URL and API token

tip

You can bind any of these commands to custom keyboard shortcuts via Preferences: Open Keyboard Shortcuts and searching for "arcan".

How the Hover Provider Works

When you hover over an environment variable reference in your code, the extension detects the pattern and shows an inline tooltip with secret metadata.

What you see when hovering over process.env.DATABASE_URL:

Arcan Secret: DATABASE_URL
Realm: production | Env: prod
Version: 3 | Updated: 2 hours ago
Value: po••••••••db (masked)

Click "Peek" to view full masked value

The hover provider caches results for 5 minutes to avoid repeated API calls. Use "Arcan: Refresh Secrets" to clear the cache.

How to Peek a Secret Without It Touching Your Clipboard

Sometimes you need to verify a secret value without risking clipboard exposure:

1. Open the command palette: Cmd+Shift+P
2. Type "Arcan: Peek Secret Value" and press Enter
3. A quick-pick menu shows all secrets in your default realm — select one
4. A notification appears with the masked value: po••••••••db
5. The value is shown in the notification only — it never touches your clipboard or any file

The notification auto-dismisses after 10 seconds. At no point is the full value displayed; you see only the first 2 and last 2 characters.

How to Insert a Secret Reference in Your Code

Instead of typing process.env.MY_SECRET manually, let the extension insert the correct pattern for your language:

1. Place your cursor where you want the reference
2. Open the command palette: Cmd+Shift+P
3. Type "Arcan: Insert Secret Reference" and press Enter
4. Select a secret from the quick-pick menu (e.g., DATABASE_URL)
5. The extension detects your file type and inserts the appropriate pattern:
   • In a .ts file: process.env.DATABASE_URL
   • In a .py file: os.environ["DATABASE_URL"]
   • In a .go file: os.Getenv("DATABASE_URL")
   • In a .sh file: ${DATABASE_URL}
   • In a .env file: DATABASE_URL=

Supported Languages and Detected Patterns

The hover provider recognizes these patterns per language:

Language	File Extensions	Detected Patterns
JavaScript	.js, .jsx, .mjs	process.env.KEY, process.env['KEY']
TypeScript	.ts, .tsx, .mts	process.env.KEY, process.env['KEY']
Python	.py	os.environ["KEY"], os.environ.get("KEY"), os.getenv("KEY")
Go	.go	os.Getenv("KEY")
Shell/Bash	.sh, .bash, .zsh	$KEY, ${KEY}, $KEY in double-quoted strings
Env files	.env, .env.*	KEY=value (left-hand side of =)
Ruby	.rb	ENV["KEY"], ENV.fetch("KEY")
Rust	.rs	std::env::var("KEY"), env::var("KEY")
Docker	Dockerfile	ENV KEY, ARG KEY
YAML	.yml, .yaml	${KEY} in value positions

Workflow: Setting Up a New Project

A step-by-step walkthrough for configuring the extension and using it in a real project:

1. Configure the connection

Cmd+Shift+P  →  "Arcan: Configure Connection"

You will be prompted for:

• Server URL: Enter your Arcan server address (e.g., https://arcan.internal:8443)
• API Token: Paste your token (arc_...). It is stored in VS Code's SecretStorage (encrypted by OS keychain), not in settings.json.

2. Set your default realm and environment

Open VS Code settings (Cmd+,) and search for "arcan":

{
  "arcan.defaultRealm": "myapp",
  "arcan.defaultEnv": "prod"
}

3. Browse secrets in the sidebar

Open the Arcan panel in the sidebar. You will see:

ARCAN SECRETS
├── myapp
│   ├── prod
│   │   ├── DATABASE_URL      (v3)
│   │   ├── REDIS_URL         (v2)
│   │   ├── STRIPE_SECRET     (v1)
│   │   └── SENTRY_DSN        (v1)
│   └── staging
│       ├── DATABASE_URL      (v1)
│       └── REDIS_URL         (v1)
└── analytics
    └── prod
        └── MIXPANEL_TOKEN    (v1)

4. Peek at a secret value

Cmd+Shift+P  →  "Arcan: Peek Secret Value"  →  Select "DATABASE_URL"

A notification appears:

Arcan: DATABASE_URL = po••••••••db

The value is masked (first 2, last 2 characters). The notification auto-dismisses after 10 seconds. The full value never touches your clipboard or any file.

5. Insert a secret reference in your code

Place your cursor in a file where you need the secret, then:

Cmd+Shift+P  →  "Arcan: Insert Secret Reference"  →  Select "DATABASE_URL"

The extension detects your file type and inserts the correct pattern:

File you are editing	What gets inserted
app.ts	process.env.DATABASE_URL
app.py	os.environ["DATABASE_URL"]
main.go	os.Getenv("DATABASE_URL")
deploy.sh	${DATABASE_URL}
.env	DATABASE_URL=
app.rb	ENV["DATABASE_URL"]
main.rs	std::env::var("DATABASE_URL")

6. Hover over references in your code

After inserting, hover over process.env.DATABASE_URL in your TypeScript file. An inline tooltip appears:

Arcan Secret: DATABASE_URL
Realm: myapp | Env: prod
Version: 3 | Updated: 2 hours ago
Value: po••••••••db (masked)

All Command Palette Commands

Open with Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux), then type any of these:

Type this	What happens
Arcan: Refresh Secrets	Reloads all secrets from the server and clears the hover cache
Arcan: Peek Secret Value	Shows a quick-pick list, then displays the masked value in a notification
Arcan: Copy Secret Value	Copies the full value to clipboard (auto-clears after 30 seconds)
Arcan: Set Secret	Prompts for key and value, then creates or updates the secret on the server
Arcan: Delete Secret	Shows a quick-pick list with a confirmation dialog before deleting
Arcan: Insert Secret Reference	Inserts a language-appropriate env var reference at your cursor position
Arcan: Configure Connection	Opens prompts to set your server URL and API token

Security

• Secret values are never shown in the tree view -- only key names
• Peek shows masked values only (first 2 and last 2 characters)
• Clipboard is automatically cleared 30 seconds after copying
• API tokens are stored in VS Code SecretStorage (encrypted by the OS keychain)
• Use valid TLS certificates in production (not self-signed)
• Use read-only tokens (arcan token create --scopes read) for applications that only need to read secrets