VJSP Command Line Interface (CLI)

Schedule agents in the terminal and efficiently complete planning, debugging, and coding work through a keyboard-only navigation method in the command line.

The VJSP CLI is built on the same underlying technology as the IDE extension plugin, enabling a consistent workflow throughout for handling agent-driven coding tasks.

Installation

bash

npm install -g @vjsp/cli

Navigate to the target working directory and run the vjsp command:

bash

# Launch an interactive conversation session
vjsp

# Launch in a specified mode
vjsp --mode architect

# Launch with a specified workspace loaded
vjsp --workspace /path/to/project

# Resume the last conversation in the current workspace
vjsp --continue

After launching the CLI, you can select an adapted model and relevant mode to start a new task.

Upgrade

Execute the following command to upgrade the VJSP CLI package:

bash

npm update -g @vjsp/cli

Core Capabilities of the VJSP CLI

Plan and execute code changes without leaving the terminal: Edit project code directly via the command line without opening an Integrated Development Environment (IDE).
Match the optimal running mode to workflow tasks: Support for official modes such as architecture design, intelligent Q&A, debugging and troubleshooting, and intelligent orchestration, as well as custom agent running modes.
Realize automated task processing: Leverage AI to assist in writing Shell scripts for various tasks such as batch renaming files in a folder and batch converting image sizes.
Extend functional boundaries through skills: Endow the tool with domain-specific professional capabilities based on Agent Skills and precipitate reusable workflows.

CLI Reference Manual

Keyboard Shortcuts

Shortcut	Description
`Ctrl+C`	Exit the tool (press twice consecutively to confirm exit)
`Ctrl+X`	Cancel the currently executing task
`Esc`	Cancel the current task during streaming responses or clear the input box
`Ctrl+Y`	Toggle fast execution mode (auto-approve all operation instructions)
`Ctrl+R`	Resume the task (only effective when the task is in a resumable state)
`!`	Enter Shell mode (only effective when the input box is empty)
`↑/↓`	Browse command history (only effective when the input box is empty)

Built-in Commands

Command	Description	Example
`vjsp`	Launch an interactive session
`/mode`	Switch running modes (Architect, Code, Ask, Debug, Orchestrator)	`/mode orchestrator`
`/model`	View the list of available models and switch models
`/model list`	List all available Large Language Models
`/model info`	Print detailed description of a model by its name	`/model info Qwen3-VJSP`
`/model select`	Select and switch to a new Large Language Model
`/checkpoint list`	List all available checkpoints
`/checkpoint restore`	Restore to a specified checkpoint (this operation is destructive)	`/checkpoint restore 41db173a`
`/tasks`	View task history
`/tasks search`	Search tasks by query keywords	`/tasks search bug fix`
`/tasks select`	Switch to a specified task	`/tasks select abc123`
`/tasks page`	Navigate to a specified page of task history	`/tasks page 2`
`/tasks next`	Navigate to the next page of task history
`/tasks prev`	Navigate to the previous page of task history
`/tasks sort`	Adjust the sorting method of task history	`/tasks sort most-expensive`
`/tasks filter`	Filter task history	`/tasks filter favorites`
`/config`	Open the configuration editor (same function as the `vjsp config` command)
`/new`	Clear historical state and launch a new agent task
`/help`	List all available commands and usage methods
`/exit`	Exit the CLI

Skills

This CLI supports agent skill capabilities, which are implemented in a lightweight format to endow AI with professional domain knowledge and standardized workflows for functional extension.

Skill file loading paths are divided into the following two categories:

Global Skills: ~/.vjsp/skills/ (callable by all projects)
Project-specific Skills: .vjsp/skills/ (only callable by the current project)

Skill effective scopes are divided into two types:

General-purpose - Effective in all running modes
Mode-specific - Only loaded in the specified running mode (e.g., code development mode, architecture design mode)

Skill File Directory Structure Example

your-project/
└── .vjsp/
    ├── skills/               # General skill directory for the current project
    │   └── project-conventions/
    │       └── SKILL.md
    └── skills-code/          # Code development mode-specific skill directory for the current project
        └── linting-rules/
            └── SKILL.md

Add a Skill

Create a skill storage directory:
bash
```
mkdir -p ~/.vjsp/skills/api-design
```
1
Create a SKILL.md file in this directory with YAML configuration information added at the top of the file:
markdown
```
---
name: api-design
description: Best Practices and Specifications for REST API Design
---

# API Design Specifications
When designing REST APIs, the following specifications must be followed...
```
1
2
3
4
5
6
7
Note: The name field in the configuration must be exactly the same as the skill directory name.
Restart the CLI session, and the newly added skill will be loaded and take effect.

Custom Commands

With custom commands, you can create reusable slash commands to execute predefined prompts with parameter replacement, simplifying repetitive tasks conveniently and standardizing workflows.

Custom command loading paths are divided into the following two categories:

Global Commands: ~/.vjsp/commands/ (callable by all projects)
Project-specific Commands: .vjsp/commands/ (only callable by the current project)

Custom commands are simple Markdown files with command attributes defined via YAML configuration information at the top.

Create a Custom Command

Create a command storage directory:

bash

mkdir -p ~/.vjsp/commands # For Windows: mkdir %USERPROFILE%\.vjsp\commands

Create a Markdown file in this directory (example: component.md):

markdown

---
description: Create a new React component
arguments:
    - ComponentName
---

Create a React component named $1 with the following contents:
- Standard TypeScript type definitions
- Basic component structure
- Component export statements
- Define a simple props interface when necessary

Place the component file in the corresponding directory according to the project directory structure.

Call the custom command in the CLI session:
bash
```
/component Button
```
1

YAML Configuration Item Description

Custom commands support the following YAML header configuration items:

description (optional): Command description, which will be displayed in the /help command
arguments (optional): List of command parameters for generating document descriptions
mode (optional): Automatically switch to the specified tool running mode when executing the command
model (optional): Automatically switch to the specified Large Language Model when executing the command

Parameter Replacement Rules

Custom commands support flexible parameter replacement capabilities with the following rules:

$ARGUMENTS: Replace with all incoming parameters concatenated by spaces
$1, $2, $3, etc.: Match a single incoming parameter by position and replace in sequence

Parameter Replacement Example:

markdown

---
description: Create a file with specified content
arguments:
    - filename
    - content
---

Create a new file named $1 with the following content:
$2

Calling method: /createfile app.ts "console.log('Hello')"

Auto Switch Mode and Model

Custom commands can be configured to automatically switch the tool mode and Large Language Model during execution, as shown in the example below:

markdown

---
description: Execute tests with coverage statistics
mode: code
model: anthropic/claude-3-5-sonnet-20241022
---

Execute the complete test suite and generate a coverage report, showing all failed test cases.
Focus on the failed test cases and provide specific repair suggestions.

When the /test command is called, the tool will automatically switch to code development mode and use the Large Language Model specified in the configuration.

Custom Command Examples

Initialize Project Documentation:

markdown

---
description: Analyze the codebase and generate an AGENTS.md document
mode: code
---

Please analyze the current codebase and generate an AGENTS.md document containing the following contents:
1. Commands for building, code checking, and testing — focusing on unit test running commands
2. Code style specifications, including import rules, formatting requirements, type definitions, and naming conventions

Focus on project-specific special specifications and non-general information discovered by reading project files.

Code Refactoring:

markdown

---
description: Refactor code to improve code quality
arguments:
    - filepath
---

Refactor the file $1, focusing on optimizing the following dimensions:
- Code readability
- Runtime performance
- Maintainability
- Type safety

Explain the modifications made in detail and the improvement of code quality brought by the modifications.

Command Priority Rules

Project-specific commands override global commands with the same name, supporting custom command behavior for individual projects while retaining default general configurations at the global level.

Checkpoint Management

VJSP automatically creates checkpoints during work to support restoring the project to any historical state.

View Checkpoints

Execute the /checkpoint list command to list all available checkpoints:

bash

/checkpoint list

The command will display the following information:

40-character full Git commit hash
Relative timestamp (e.g., 5 minutes ago, 2 hours ago)
Auto-saved checkpoints will be marked with [auto-saved]

Restore to a Checkpoint

Restore the project to a specified checkpoint using the full Git hash:

bash

/checkpoint restore 00d185d5020969752bc9ae40823b9d6a723696e2

⚠️ Warning

Checkpoint restoration is a destructive operation that will have the following effects after execution:

Perform a Git hard reset, and all uncommitted changes will be lost
Delete all conversation records after the checkpoint
The operation cannot be undone after execution

Before restoration, ensure that all work content to be retained has been committed or backed up.

Command Alias: /cp can be used as a shorthand for /checkpoint

Task History Management

You can directly view, search, and browse task history in the CLI.

View Task History

Execute the /tasks command to display task history:

bash

/tasks

The command will display the following information:

Task number and task description
Task ID (for task switching)
Relative timestamp

Token usage
Favorite task mark (⭐)
Pagination identifier (10 tasks displayed per page)

Search for Tasks

Search for specified tasks by keywords:

bash

/tasks search bug fix
/tasks search implement feature

Search results will be automatically sorted by relevance.

Switch Tasks

Switch to a specified task using the task ID:

bash

/tasks select abc123

The command will load the complete conversation history of the task and restore the task context.

Pagination Browsing

Browse different pages of task history:

bash

/tasks page 2      # Navigate to page 2
/tasks next        # Navigate to the next page
/tasks prev        # Navigate to the previous page

Task Sorting

Sort task history by different dimensions:

bash

/tasks sort newest          # Sort by creation time from newest to oldest (default rule)
/tasks sort oldest          # Sort by creation time from oldest to newest
/tasks sort most-tokens     # Sort by token usage from most to least
/tasks sort most-relevant   # Sort by relevance (only effective during search)

Task Filtering

Filter tasks by workspace or favorite status:

bash

/tasks filter current    # Display only tasks in the current workspace
/tasks filter all        # Display tasks in all workspaces
/tasks filter favorites  # Display only favorite tasks
/tasks filter all-tasks  # Display all tasks (clear filter conditions)

Command Alias: /t and /history can be used as shorthands for /tasks

Model Provider Configuration Reference

VJSP supports configuring self-owned keys for Large Language Model providers and AI gateways, with different configuration items for different providers.

To edit the configuration file manually, execute the following command:

bash

vjsp config

Complete the configuration through the interactive command line process.

💡 Tip

You can also execute the /config slash command in the interactive session, which has the same function as the vjsp config command.

Parallel Mode

Parallel mode supports launching multiple VJSP instances in the same directory to process tasks in parallel without conflicts, and you can launch any number of instances as needed! After the tasks are completed, all modifications will be synced to independent Git branches.

bash

# Prerequisite: The current directory must be a valid Git repository

# In interactive mode, branch modifications will be automatically committed on exit
# Terminal 1
vjsp --parallel "improve xyz"
# Terminal 2
vjsp --parallel "improve abc"

# More efficient when used with auto mode 🚀
# Terminal 1
vjsp --parallel --auto "improve xyz"
# Terminal 2
vjsp --parallel --auto "improve abc"

Auto-approval Configuration

After enabling the auto-approval feature, the VJSP CLI will execute operations without manual user confirmation. This configuration can be set step by step in interactive mode, or completed via the vjsp config command or direct editing of the configuration file ~/.vjsp/config.json.

Default Auto-approval Configuration

json

{
	"autoApproval": {
		"enabled": true,
		"read": {
			"enabled": true,
			"outside": false
		},
		"write": {
			"enabled": true,
			"outside": false,
			"protected": false
		},
		"execute": {
			"enabled": true,
			"allowed": ["npm", "git", "pnpm"],
			"denied": ["rm -rf", "sudo"]
		},
		"browser": {
			"enabled": false
		},
		"mcp": {
			"enabled": true
		},
		"mode": {
			"enabled": true
		},
		"subtasks": {
			"enabled": true
		},
		"question": {
			"enabled": false,
			"timeout": 60
		},
		"retry": {
			"enabled": true,
			"delay": 10
		},
		"todo": {
			"enabled": true
		}
	}
}

Configuration Item Description

read: Auto-approval configuration for file read operations
- outside: Whether to allow reading files outside the workspace
write: Auto-approval configuration for file write operations
- outside: Whether to allow writing files outside the workspace
- protected: Whether to allow modifying protected files (e.g., package.json)
execute: Auto-approval configuration for command execution operations
- allowed: List of command matching rules allowed for execution (e.g., ["npm", "git"])
- denied: List of command matching rules prohibited for execution (with higher priority than allowed rules)
browser: Auto-approval configuration for browser operations
mcp: Auto-approval configuration for MCP tool calls
mode: Auto-approval configuration for tool mode switching
subtasks: Auto-approval configuration for subtask creation
question: Auto-approval configuration for subsequent question responses
retry: Auto-approval configuration for API request retries
todo: Auto-approval configuration for to-do list updates

Command Approval Matching Rules

The execute.allowed and execute.denied lists support hierarchical command matching rules as follows:

Basic command: "git" matches all git subcommands (e.g., git status, git commit, git push)
Command + subcommand: "git status" matches all git status-related commands (e.g., git status --short, git status -v)
Exact command: "git status --short" matches only this exact command

Matching Rule Example:

json

{
	"execute": {
		"enabled": true,
		"allowed": [
			"npm", // Allow all npm commands
			"git status", // Allow all git status-related commands
			"ls -la" // Allow only the exact execution of the "ls -la" command
		],
		"denied": [
			"git push --force" // Prohibit this exact command even if git commands are allowed
		]
	}
}

Interactive Mode

Running VJSP without the --auto parameter enters interactive mode by default, which is specially designed for console interactive collaboration between users and the tool.

In interactive mode, when the tool executes an operation without auto-approval configuration, it will send an approval request to the user. The user can review the operation content before confirming execution, or choose to add the operation to the auto-approval list.

Interactive Command Approval

In interactive mode, command approval requests will display hierarchical operation options, as shown in the example below:

[!] Manual confirmation required for the operation:
> ✓ Execute command (y)
  ✓ Always allow execution of all git commands (1)
  ✓ Always allow execution of git status-related commands (2)
  ✓ Always allow execution of the exact git status --short --branch command (3)
  ✗ Reject execution (n)

Selecting any "Always allow" option will perform the following operations:

Approve and execute the current command
Add the matching rule of the command to the execute.allowed list in the configuration file
Subsequent commands matching this rule will be auto-approved for execution

In this way, the auto-approval rules can be improved step by step without manually editing the configuration file.

Autonomous Mode (Non-interactive)

Autonomous mode supports VJSP running in automated environments such as CI/CD pipelines without human interaction.

bash

# Run in autonomous mode and pass in task prompts
vjsp --auto "Implement feature X"

# Run in autonomous mode and pass in task prompts via pipeline
echo "Fix the bug in app.ts" | vjsp --auto

# Run in autonomous mode with a set timeout (unit: seconds)
vjsp --auto "Run tests" --timeout 300

# Run in autonomous mode and output results in JSON format (for structured parsing)
vjsp --auto --json "Implement feature X"

Autonomous Mode Running Features

After adding the --auto parameter to enter autonomous mode, the tool will exhibit the following features:

No human interaction: All operation approval requests are automatically processed according to the configuration
Auto-approve/reject: Automatically determine whether an operation is allowed to execute based on the auto-approval configuration
Auto-response to subsequent questions: The tool will automatically send instructions to the AI to request independent decision-making for responding to subsequent questions
Auto-exit after task completion: The CLI will automatically exit after the task is completed or times out

JSON Output Mode

Using the --json parameter with the --auto parameter, the tool will output structured JSON results instead of the default terminal interactive interface, which is suitable for programmatic integration and result parsing of the tool.

bash

# Standard autonomous mode, displaying the terminal interactive interface
vjsp --auto "Fix the bug"

# Autonomous mode, outputting results in JSON format
vjsp --auto --json "Fix the bug"

# Combined with pipeline input, outputting results in JSON format
echo "Implement feature X" | vjsp --auto --json

Usage Requirements:

The --json parameter must be used with the --auto parameter
Results will be output to the standard output stream (stdout) in structured JSON format for easy parsing
Suitable for CI/CD pipelines and various automated workflows

Auto-approval Rules for Autonomous Mode

Autonomous mode will strictly follow the Auto-approval Configuration, and operations without auto-approval configuration will be prohibited from execution.

Subsequent Question Handling in Autonomous Mode

In autonomous mode, when the AI raises subsequent questions, the tool will automatically send the following response instruction:

"The current process is running in non-interactive autonomous mode, and the user cannot participate in decision-making. Please make independent decisions and continue execution."

This instruction will guide the AI to advance the task independently without manual input.

Exit Code Description

0: Execution successful (task completed)
124: Execution timed out (the task exceeded the set time limit)
1: Execution failed (an error occurred during tool initialization or task execution)

CI/CD Integration Example

yaml

# GitHub Actions Integration Example
- name: Run VJSP
  run: |
      echo "Implement the new feature" | vjsp --auto --timeout 600

Session Resumption

Use the --continue (or shorthand -c) parameter to resume the last conversation session in the current workspace:

bash

# Resume the most recent task in the current workspace
vjsp --continue
vjsp -c

Feature Characteristics

Automatically identify the most recent task in the current workspace
Load the complete conversation history of the task
Support resuming execution from where the task was interrupted
Cannot be used with the --auto mode or task prompt parameters at the same time
Will throw an error and exit if there is no historical task in the current workspace

Workflow Example

bash

# Launch a new task
vjsp
# > Enter task prompt: "Create a REST API"
# ... Perform task operations ...
# Execute the /exit command to exit the tool

# To continue completing the task later
vjsp --continue
# The tool will restore the conversation history and you can continue executing the task directly

Usage Restrictions

Cannot be used with the --auto mode
Cannot be used with task prompt parameters at the same time <<<<<<< HEAD
Only effective when there are historical tasks in the current workspace

=======

Only effective when there are historical tasks in the current workspace

6e63aff8ec8ee8d1258b0a21bd15120df33ce839

VJSP Command Line Interface (CLI) ​

Installation ​

Upgrade ​

Core Capabilities of the VJSP CLI ​

CLI Reference Manual ​

Keyboard Shortcuts ​

Built-in Commands ​

Skills ​

Skill File Directory Structure Example ​

Add a Skill ​

Custom Commands ​

Create a Custom Command ​

YAML Configuration Item Description ​

Parameter Replacement Rules ​

Auto Switch Mode and Model ​

Custom Command Examples ​

Command Priority Rules ​

Checkpoint Management ​

View Checkpoints ​

Restore to a Checkpoint ​

Task History Management ​

View Task History ​

Search for Tasks ​

Switch Tasks ​

Pagination Browsing ​

Task Sorting ​

Task Filtering ​

Model Provider Configuration Reference ​

Parallel Mode ​

Auto-approval Configuration ​

Default Auto-approval Configuration ​

Configuration Item Description ​

Command Approval Matching Rules ​

Interactive Mode ​

Interactive Command Approval ​

Autonomous Mode (Non-interactive) ​

Autonomous Mode Running Features ​

JSON Output Mode ​

Auto-approval Rules for Autonomous Mode ​

Subsequent Question Handling in Autonomous Mode ​

Exit Code Description ​

CI/CD Integration Example ​

Session Resumption ​

Feature Characteristics ​

Workflow Example ​

Usage Restrictions ​

VJSP Command Line Interface (CLI)

Installation

Upgrade

Core Capabilities of the VJSP CLI

CLI Reference Manual

Keyboard Shortcuts

Built-in Commands

Skills

Skill File Directory Structure Example

Add a Skill

Custom Commands

Create a Custom Command

YAML Configuration Item Description

Parameter Replacement Rules

Auto Switch Mode and Model

Custom Command Examples

Command Priority Rules

Checkpoint Management

View Checkpoints

Restore to a Checkpoint

Task History Management

View Task History

Search for Tasks

Switch Tasks

Pagination Browsing

Task Sorting

Task Filtering

Model Provider Configuration Reference

Parallel Mode

Auto-approval Configuration

Default Auto-approval Configuration

Configuration Item Description

Command Approval Matching Rules

Interactive Mode

Interactive Command Approval

Autonomous Mode (Non-interactive)

Autonomous Mode Running Features

JSON Output Mode

Auto-approval Rules for Autonomous Mode

Subsequent Question Handling in Autonomous Mode

Exit Code Description

CI/CD Integration Example

Session Resumption

Feature Characteristics

Workflow Example

Usage Restrictions