fileglide 0.0.1

Agent-oriented filesystem CLI for precise, Chinese-friendly file and path operations with stronger non-ASCII support.

FileGlide

Agent-oriented filesystem CLI for precise, Chinese-friendly file and path operations with stronger non-ASCII support.

Traverse trees, inspect sizes, search names and content, edit exact line ranges, handle binary payloads, and execute explicit batch plans from one consistent command tree.

Installation | Agent Skills | Quick Start | Command Tree | Output and Encoding | Search and Editing | Batch Execution | More Docs

English | 简体中文 | 繁體中文

Installation

Install the published PyPI package fileglide. The package exposes the fileglide CLI directly after installation.

uv add -U fileglide
fileglide --help

pip install -U fileglide
fileglide --help

Python 3.10+ is required. The CLI is implemented with click and exposes JSON as the default output contract.

Agent Skills

FileGlide also provides agent skills for Codex, Claude Code, and other coding agents.

When you want an agent to install them, just say:

Please install skills from https://github.com/vortezwohl/fileglide, and place them in my global user skill directory.

These skills are intended for repository workflows built around constrained filesystem access, precise text editing, OpenSpec change management, and verifiable step-by-step execution.

Quick Start

1. Create a scoped workspace path

fileglide path create 'tests/tmp/demo/docs' --root 'D:\github-project\fileglide' --parents --exist-ok

Use --root to keep all relative paths constrained to a known workspace root.

2. Create and write a text file

fileglide file create 'tests/tmp/demo/docs/notes.txt' --root 'D:\github-project\fileglide' --parents --exist-ok
fileglide text write 'tests/tmp/demo/docs/notes.txt' --root 'D:\github-project\fileglide' --mode overwrite --content "alpha`nbravo`ncharlie"

Use overwrite, append, or insert modes to control how text mutations are applied.

3. Read exact line ranges

fileglide text read 'tests/tmp/demo/docs/notes.txt' --root 'D:\github-project\fileglide' --start-line 2 --end-line 3

This is useful when an agent needs precise context instead of loading an entire file.

4. Search file content with regex

fileglide text grep 'bravo|charlie' 'tests/tmp/demo' --root 'D:\github-project\fileglide' --include '*.txt'

Content search supports regular expressions and scoped traversal.

5. Fuzzy search file names

fileglide file search 'note' 'tests/tmp/demo' --root 'D:\github-project\fileglide' --mode fuzzy

Fuzzy filename and pathname matching is powered by vortezwohl Levenshtein distance utilities.

Command Tree

Command	Role	Typical use
file	File lifecycle and file-only traversal	Create, delete, list, test existence, and search files
path	Directory lifecycle and path-only traversal	Create, delete, list, test existence, and search directories
tree	Mixed tree traversal	Return both files and directories from a scoped start path
text	Text and binary content operations	Read, write, grep, replace line ranges, insert by anchor, and copy binary payloads
inspect	Size and byte inspection	Measure file or directory size and read binary-safe byte slices
batch	Explicit batch execution	Validate and execute JSON plans step by step

Output and Encoding

Current public-facing defaults:

• --format json
• --pretty
• scoped path resolution through --root
• UTF-8 without BOM works directly
• common encodings such as UTF-8 BOM, UTF-16 LE, GBK, GB18030, and Shift-JIS are detected and handled in the text workflow
• binary commands keep payloads binary-safe instead of forcing text decoding

Practical notes:

• Use --format text when a human-readable console summary is preferable.
• Keep json for scripts, automation, and agent tool invocation.
• Text commands can force an encoding explicitly with --encoding.
• Binary write and byte-slice inspection avoid accidental corruption of non-text data.

Search and Editing

Representative editing and search operations:

fileglide text write 'tests/tmp/demo/docs/notes.txt' --root 'D:\github-project\fileglide' --mode append --content "`ndelta"
fileglide text write 'tests/tmp/demo/docs/notes.txt' --root 'D:\github-project\fileglide' --mode insert --position 6 --content '[INSERT]'
fileglide text replace-lines 'tests/tmp/demo/docs/notes.txt' --root 'D:\github-project\fileglide' --start-line 2 --end-line 2 --content 'BRAVO'
fileglide text insert-anchor 'tests/tmp/demo/docs/notes.txt' --root 'D:\github-project\fileglide' --after --anchor 'BRAVO' --content "`nANCHOR-INSERT"

fileglide path search 'doc' 'tests/tmp/demo' --root 'D:\github-project\fileglide' --mode fuzzy --kind directory
fileglide tree list 'tests/tmp/demo' --root 'D:\github-project\fileglide' --kind all
fileglide inspect size 'tests/tmp/demo' --root 'D:\github-project\fileglide'

These commands are designed for AI agents that need exact, local, and verifiable filesystem actions instead of ad hoc shell parsing.

Batch Execution

fileglide supports explicit JSON plans for grouped operations.

Example plan shape:

{
  "steps": [
    {
      "action": "path.create",
      "params": {
        "target": "tests/tmp/batch-demo",
        "root": "D:\\github-project\\fileglide",
        "parents": true,
        "exist_ok": true
      }
    },
    {
      "action": "text.write",
      "params": {
        "target": "tests/tmp/batch-demo/readme.txt",
        "root": "D:\\github-project\\fileglide",
        "mode": "overwrite",
        "content": "batch-ready"
      }
    }
  ]
}

Preview first, then apply when the plan looks correct:

fileglide batch run 'D:\github-project\fileglide\tests\fixtures\batch\sample-plan.json' --dry-run
fileglide batch run 'D:\github-project\fileglide\tests\fixtures\batch\sample-plan.json' --apply

More Docs

• Architecture and project design
• 简体中文 README
• 繁體中文 README

License

MIT License.