Skip to content

cli-reference.md

Latest commit

 

History

History
267 lines (206 loc) · 6.08 KB

cli-reference.md

File metadata and controls

267 lines (206 loc) · 6.08 KB

CLI Reference

Command-line tools for py-code-mode.

MCP Server

The MCP server exposes py-code-mode to Claude Code and other MCP clients.

Installation

# Add to Claude Code
claude mcp add py-code-mode -- uvx --from git+https://github.com/xpcmdshell/py-code-mode.git@v0.11.0 py-code-mode-mcp --base ~/.code-mode

Usage

py-code-mode-mcp [OPTIONS]

Options

Flag Description Default
--base PATH Base directory with tools/, workflows/, artifacts/ subdirs -
--storage PATH Path to storage directory (workflows, artifacts) -
--tools PATH Path to tools directory (YAML definitions) -
--redis URL Redis URL for storage -
--prefix PREFIX Redis key prefix py-code-mode
--timeout SECONDS Code execution timeout unlimited
--no-runtime-deps Disable runtime dependency installation false
--no-sync-deps Don't install pre-configured deps on startup false

Examples

# Base directory (auto-discovers tools/, workflows/, artifacts/)
py-code-mode-mcp --base ~/.code-mode

# Explicit storage + tools paths
py-code-mode-mcp --storage ./data --tools ./project/tools

# Redis storage with timeout
py-code-mode-mcp --redis redis://localhost:6379 --prefix my-agent --timeout 60

# Production: locked down deps
py-code-mode-mcp --base ~/.code-mode --no-runtime-deps

Exposed MCP Tools

When running, the server exposes these tools to MCP clients:

Tool Description
run_code Execute Python with access to tools, workflows, artifacts, deps
list_tools List available tools
search_tools Semantic search for tools
list_workflows List available workflows
search_workflows Semantic search for workflows
create_workflow Save a new workflow
delete_workflow Remove a workflow
list_artifacts List saved artifacts
list_deps List configured dependencies
add_dep Add and install a dependency (if --no-runtime-deps not set)
remove_dep Remove a dependency (if --no-runtime-deps not set)

Store CLI

Manage workflows, tools, and dependencies in Redis stores.

Usage

python -m py_code_mode.cli.store <command> [OPTIONS]

Commands

bootstrap

Push workflows, tools, or deps from local files to a store.

python -m py_code_mode.cli.store bootstrap \
  --source PATH \
  --target URL \
  --prefix PREFIX \
  [--type workflows|tools|deps] \
  [--clear] \
  [--deps "pkg1" "pkg2"]
Option Description Default
--source PATH Source directory or requirements file required
--target URL Target store URL (e.g., redis://localhost:6379) required
--prefix PREFIX Key prefix for items workflows
--type TYPE Type of items: workflows, tools, or deps workflows
--clear Remove existing items before adding false
--deps Inline package specs (for deps only) -

Examples:

# Bootstrap workflows
python -m py_code_mode.cli.store bootstrap \
  --source ./workflows \
  --target redis://localhost:6379 \
  --prefix my-agent

# Bootstrap tools
python -m py_code_mode.cli.store bootstrap \
  --source ./tools \
  --target redis://localhost:6379 \
  --prefix my-agent \
  --type tools

# Bootstrap deps from requirements file
python -m py_code_mode.cli.store bootstrap \
  --source requirements.txt \
  --target redis://localhost:6379 \
  --prefix my-agent \
  --type deps

# Bootstrap deps inline
python -m py_code_mode.cli.store bootstrap \
  --target redis://localhost:6379 \
  --prefix my-agent \
  --type deps \
  --deps "requests>=2.31" "pandas>=2.0"

# Replace all existing workflows
python -m py_code_mode.cli.store bootstrap \
  --source ./workflows \
  --target redis://localhost:6379 \
  --prefix my-agent \
  --clear

list

List items in a store.

python -m py_code_mode.cli.store list \
  --target URL \
  --prefix PREFIX \
  [--type workflows|tools|deps]

Examples:

# List workflows
python -m py_code_mode.cli.store list \
  --target redis://localhost:6379 \
  --prefix my-agent

# List tools
python -m py_code_mode.cli.store list \
  --target redis://localhost:6379 \
  --prefix my-agent \
  --type tools

# List deps
python -m py_code_mode.cli.store list \
  --target redis://localhost:6379 \
  --prefix my-agent \
  --type deps

pull

Retrieve workflows from a store to local files.

python -m py_code_mode.cli.store pull \
  --target URL \
  --prefix PREFIX \
  --dest PATH

Example:

# Pull workflows to review agent-created ones
python -m py_code_mode.cli.store pull \
  --target redis://localhost:6379 \
  --prefix my-agent \
  --dest ./workflows-from-redis

diff

Compare local workflows vs remote store.

python -m py_code_mode.cli.store diff \
  --source PATH \
  --target URL \
  --prefix PREFIX

Example:

# See what agent added or changed
python -m py_code_mode.cli.store diff \
  --source ./workflows \
  --target redis://localhost:6379 \
  --prefix my-agent

Output shows:

  • + name - Agent-created (in store, not local)
  • - name - Removed from store (local only)
  • ~ name - Modified
  • = name - Unchanged

CI/CD Patterns

Deploy Workflows to Production

# In CI pipeline
python -m py_code_mode.cli.store bootstrap \
  --source ./workflows \
  --target $REDIS_URL \
  --prefix production \
  --clear

Review Agent Creations

# Pull what agents created
python -m py_code_mode.cli.store pull \
  --target $REDIS_URL \
  --prefix production \
  --dest ./review

# Compare to source
python -m py_code_mode.cli.store diff \
  --source ./workflows \
  --target $REDIS_URL \
  --prefix production

Pre-configure Dependencies

# Bootstrap deps to Redis
python -m py_code_mode.cli.store bootstrap \
  --source requirements.txt \
  --target $REDIS_URL \
  --prefix production \
  --type deps

# Then run MCP server with --no-runtime-deps to lock it down
py-code-mode-mcp --redis $REDIS_URL --prefix production --no-runtime-deps