Skip to main content
The workspace command group manages semantic code search, allowing you to index directories and perform intelligent queries across your codebase.

​
Usage

forge workspace [SUBCOMMAND] [OPTIONS]

​
Subcommands

​
sync

Synchronize a directory for semantic search by indexing its contents. 
forge workspace sync [PATH] [OPTIONS]
​
path
path
default:"."
Path to the directory to sync. Defaults to current directory.
forge workspace sync
forge workspace sync ~/projects/myapp
forge workspace sync /path/to/repo
​
--batch-size
number
default:"100"
Number of files to process concurrently.
forge workspace sync --batch-size 50
forge workspace sync . --batch-size 200

​
list

List all indexed workspaces. 
forge workspace list [OPTIONS]
​
--porcelain
boolean
default:"false"
Output in machine-readable format.Alias: -p
forge workspace list --porcelain
forge workspace list -p

​
query

Query the workspace using semantic search. 
forge workspace query <QUERY> [PATH] [OPTIONS]
​
query
string
required
Search query.
forge workspace query "authentication logic"
forge workspace query "error handling"
​
path
path
default:"."
Path to the directory to search. Defaults to current directory.
forge workspace query "database queries" .
forge workspace query "API endpoints" ~/projects/api
​
--limit
number
default:"10"
Maximum number of results to return.Alias: -l
forge workspace query "tests" -l 20
forge workspace query "config" --limit 5
​
--top-k
number
default:"none"
Number of highest probability tokens to consider (1-1000).
forge workspace query "imports" --top-k 100
​
--use-case
string
required
Describe your intent or goal to filter results for relevance.Alias: -r
forge workspace query "http" -r "finding API route handlers"
forge workspace query "test" --use-case "locating integration tests"
​
--starts-with
string
default:"none"
Filter results to files starting with this prefix.
forge workspace query "utils" --starts-with src/
forge workspace query "config" --starts-with packages/core
​
--ends-with
string
default:"none"
Filter results to files ending with this suffix.
forge workspace query "tests" --ends-with .test.ts
forge workspace query "types" --ends-with .d.ts

​
info

Show workspace information for an indexed directory. 
forge workspace info [PATH]
​
path
path
default:"."
Path to the directory to get information for. Defaults to current directory.
forge workspace info
forge workspace info ~/projects/myapp

​
delete

Delete one or more workspaces. 
forge workspace delete <WORKSPACE_ID>...
​
workspace_ids
string[]
required
Workspace IDs to delete. Multiple IDs can be specified.
forge workspace delete abc123
forge workspace delete abc123 def456 ghi789

​
status

Show sync status of all files in the workspace. 
forge workspace status [PATH] [OPTIONS]
​
path
path
default:"."
Path to the directory to check status for. Defaults to current directory.
forge workspace status
forge workspace status ~/projects/myapp
​
--porcelain
boolean
default:"false"
Output in machine-readable format.Alias: -p
forge workspace status --porcelain
forge workspace status . -p

​
init

Initialize an empty workspace for the provided directory. 
forge workspace init [PATH]
​
path
path
default:"."
Path to the directory to initialize as a workspace. Defaults to current directory.
forge workspace init
forge workspace init ~/projects/newapp

​
Examples

​
Sync Current Directory

forge workspace sync
Example output: 
Indexing workspace: /home/user/projects/myapp

▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100%

✓ Indexed 1,247 files in 23 seconds

​
Sync with Custom Batch Size

forge workspace sync ~/projects/large-repo --batch-size 200

​
List All Workspaces

forge workspace list
Example output: 
Indexed Workspaces:

ID       Path                              Files   Last Synced
abc123   /home/user/projects/myapp        1,247   2024-01-15 10:23
def456   /home/user/projects/api          856     2024-01-14 16:45
ghi789   /home/user/projects/frontend     2,341   2024-01-13 09:12

​
Query Workspace

forge workspace query "authentication logic" -r "finding login implementation"
Example output: 
Search Results:

1. src/auth/login.ts (score: 0.94)
   Implementation of user authentication and session management

2. src/middleware/auth.ts (score: 0.87)
   Authentication middleware for API routes

3. tests/auth.test.ts (score: 0.82)
   Integration tests for authentication flow

​
Query with Filters

forge workspace query "error handling" \
  --limit 5 \
  --starts-with src/ \
  --ends-with .ts \
  -r "finding error handling patterns"

​
View Workspace Status

forge workspace status
Example output: 
Workspace Status: /home/user/projects/myapp

Status      Files
Indexed     1,247
Modified    3
New         5
Deleted     2

Out of sync files:
  M  src/auth/login.ts
  M  src/api/users.ts
  M  README.md
  A  src/utils/new-helper.ts
  A  tests/new-test.test.ts
  D  old-file.ts

Run 'forge workspace sync' to update the index.

​
Get Workspace Info

forge workspace info
Example output: 
Workspace Information:

  ID:           abc123
  Path:         /home/user/projects/myapp
  Files:        1,247
  Total size:   12.4 MB
  Last synced:  2024-01-15 10:23
  Created:      2024-01-10 14:30

​
Delete Workspace

forge workspace delete abc123
Example output: 
✓ Workspace deleted: abc123

​
Initialize New Workspace

forge workspace init ~/projects/newapp
Example output: 
✓ Workspace initialized: /home/user/projects/newapp
  Run 'forge workspace sync' to index files.

​
Use Cases

​
Finding Specific Code Patterns

forge workspace query "database migrations" \
  -r "locating migration files" \
  --ends-with .sql

​
Locating Test Files

forge workspace query "user authentication" \
  -r "finding relevant test files" \
  --starts-with tests/ \
  --ends-with .test.ts

​
Exploring New Codebase

forge workspace query "entry point" \
  -r "finding main application entry points" \
  --limit 3

​
Machine-Readable Output

forge workspace list --porcelain | jq '.workspaces[] | select(.files > 1000)'
forge workspace status --porcelain

​
Storage Location

Workspace indexes are stored in: 
~/.local/share/forge/workspaces/

​
Performance Tips

  • Use --batch-size to adjust indexing speed based on your system
  • Larger batch sizes (200-500) work well for SSDs
  • Smaller batch sizes (50-100) may be better for HDDs
  • Re-sync periodically to keep the index up to date
  • forge - AI assistant can use workspace search automatically
  • forge list workspace - Alternative way to list workspaces

​
Notes

  • Workspaces must be synced before querying
  • The sync command respects .gitignore files
  • Semantic search uses AI embeddings for intelligent matching
  • Query results are ranked by relevance
  • Use --use-case to improve result relevance
  • File filters (--starts-with, --ends-with) narrow results efficiently

Build docs developers (and LLMs) love

Get started for freeTalk to us