Skip to content

Commit 7531ec2

Browse files
butschsterbutschster
authored
Merge pull request #24 from context-hub/issue/308
docs: add project:remove command and update project management docs
2 parents 9b712fc + a9ce181 commit 7531ec2

2 files changed

Lines changed: 275 additions & 33 deletions

File tree

‎docs/getting-started/command-reference.md‎

Lines changed: 157 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -546,7 +546,8 @@ redeployment.
546546

547547
## RAG Knowledge Store Commands
548548

549-
Commands for managing the RAG (Retrieval-Augmented Generation) knowledge store. These commands require RAG to be configured in your `context.yaml`.
549+
Commands for managing the RAG (Retrieval-Augmented Generation) knowledge store. These commands require RAG to be
550+
configured in your `context.yaml`.
550551

551552
### Check RAG Status
552553

@@ -558,9 +559,9 @@ ctx rag:status
558559

559560
#### Options
560561

561-
| Option | Description |
562-
|----------|------------------|
563-
| `--json` | Output as JSON |
562+
| Option | Description |
563+
|----------|----------------|
564+
| `--json` | Output as JSON |
564565

565566
```bash
566567
ctx rag:status --json
@@ -576,12 +577,12 @@ ctx rag:index <path>
576577

577578
#### Options
578579

579-
| Option | Short | Default | Description |
580-
|---------------|-------|-----------|------------------------------------------------|
581-
| `--pattern` | `-p` | `*.md` | File pattern (e.g., `*.php`, `*.md`) |
582-
| `--type` | `-t` | `general` | Document type (see below) |
583-
| `--recursive` | `-r` | `true` | Search recursively |
584-
| `--dry-run` | | `false` | Preview files without indexing |
580+
| Option | Short | Default | Description |
581+
|---------------|-------|-----------|--------------------------------------|
582+
| `--pattern` | `-p` | `*.md` | File pattern (e.g., `*.php`, `*.md`) |
583+
| `--type` | `-t` | `general` | Document type (see below) |
584+
| `--recursive` | `-r` | `true` | Search recursively |
585+
| `--dry-run` | | `false` | Preview files without indexing |
585586

586587
**Document types:** `architecture`, `api`, `testing`, `convention`, `tutorial`, `reference`, `general`
587588

@@ -611,9 +612,9 @@ ctx rag:clear
611612

612613
#### Options
613614

614-
| Option | Short | Description |
615-
|-----------|-------|-----------------------------|
616-
| `--force` | `-f` | Skip confirmation prompt |
615+
| Option | Short | Description |
616+
|-----------|-------|--------------------------|
617+
| `--force` | `-f` | Skip confirmation prompt |
617618

618619
```bash
619620
ctx rag:clear -f
@@ -629,12 +630,12 @@ ctx rag:reindex <path>
629630

630631
#### Options
631632

632-
| Option | Short | Default | Description |
633-
|---------------|-------|-----------|-----------------------------------|
634-
| `--pattern` | `-p` | `*.md` | File pattern |
635-
| `--type` | `-t` | `general` | Document type |
636-
| `--recursive` | `-r` | `true` | Search recursively |
637-
| `--force` | `-f` | `false` | Skip confirmation prompt |
633+
| Option | Short | Default | Description |
634+
|---------------|-------|-----------|--------------------------|
635+
| `--pattern` | `-p` | `*.md` | File pattern |
636+
| `--type` | `-t` | `general` | Document type |
637+
| `--recursive` | `-r` | `true` | Search recursively |
638+
| `--force` | `-f` | `false` | Skip confirmation prompt |
638639

639640
#### Examples
640641

@@ -646,4 +647,140 @@ ctx rag:reindex docs -t reference
646647
ctx rag:reindex docs -f
647648
```
648649

649-
> **Note:** For detailed RAG configuration and MCP tool usage, see the [RAG Knowledge Store](/mcp/rag) documentation.
650+
> **Note:** For detailed RAG configuration and MCP tool usage, see the [RAG Knowledge Store](/mcp/rag) documentation.
651+
652+
## Project Management Commands
653+
654+
Commands for managing multiple projects. These allow you to register, switch between, list, and remove projects from the
655+
CTX registry.
656+
657+
> **Note:** For detailed project management information, see the [Dynamic Project Switching](/mcp/projects)
658+
> documentation.
659+
660+
### Add a Project (`project:add`)
661+
662+
Register a new project with the system:
663+
664+
```bash
665+
ctx project:add <path> [--name=<alias>] [--config-file=<path>] [--env-file=<path>] [--switch]
666+
```
667+
668+
#### Arguments
669+
670+
| Argument | Description |
671+
|----------|---------------------------------------------------------------|
672+
| `path` | Path to the project directory. Use `.` for current directory. |
673+
674+
#### Options
675+
676+
| Option | Short | Description |
677+
|-----------------|-------|------------------------------------------------------|
678+
| `--name` | | Alias name for the project |
679+
| `--config-file` | `-c` | Path to custom configuration file within the project |
680+
| `--env-file` | `-e` | Path to .env file within the project |
681+
| `--switch` | `-s` | Switch to this project after adding it |
682+
683+
#### Examples
684+
685+
```bash
686+
# Add current directory as a project
687+
ctx project:add . --name=my-project
688+
689+
# Add with custom configuration
690+
ctx project:add /path/to/project --name=backend --env-file=.env.dev
691+
692+
# Add and switch to the project
693+
ctx project:add . --name=frontend --switch
694+
```
695+
696+
### Switch Project (`project`)
697+
698+
Switch to a different registered project:
699+
700+
```bash
701+
ctx project [<path_or_alias>]
702+
```
703+
704+
#### Arguments
705+
706+
| Argument | Description |
707+
|-----------------|-------------------------------------------------------------------|
708+
| `path_or_alias` | Path or alias to the project. If omitted, shows interactive menu. |
709+
710+
#### Examples
711+
712+
```bash
713+
# Switch using alias
714+
ctx project my-backend
715+
716+
# Switch using path
717+
ctx project /path/to/project
718+
719+
# Interactive selection
720+
ctx project
721+
```
722+
723+
### List Projects (`project:list`)
724+
725+
View all registered projects:
726+
727+
```bash
728+
ctx project:list
729+
# or
730+
ctx projects
731+
```
732+
733+
#### Example Output
734+
735+
```
736+
╭─● CURRENT ─────────────────────────────────────────────────────────╮
737+
│ /home/user/projects/my-app
738+
│ Aliases: my-app
739+
│ Added: Jan 18, 2025
740+
╰────────────────────────────────────────────────────────────────────╯
741+
742+
╭─○──────────────────────────────────────────────────────────────────╮
743+
│ /home/user/projects/backend
744+
│ Aliases: backend
745+
│ Added: Jan 15, 2025
746+
╰────────────────────────────────────────────────────────────────────╯
747+
748+
Commands:
749+
ctx project <path|alias> Switch to a project
750+
ctx project:add <path> Add a new project
751+
ctx project:remove <path|alias> Remove a project
752+
```
753+
754+
### Remove a Project (`project:remove`)
755+
756+
Remove a project from the registry:
757+
758+
```bash
759+
ctx project:remove [<path_or_alias>] [--force]
760+
```
761+
762+
#### Arguments
763+
764+
| Argument | Description |
765+
|-----------------|-------------------------------------------------------------------|
766+
| `path_or_alias` | Path or alias to the project. If omitted, shows interactive menu. |
767+
768+
#### Options
769+
770+
| Option | Short | Description |
771+
|------------------|-------|----------------------------------------------|
772+
| `--force` | `-f` | Skip confirmation prompt |
773+
| `--keep-aliases` | | Keep aliases when removing (not recommended) |
774+
775+
#### Examples
776+
777+
```bash
778+
# Remove by alias
779+
ctx project:remove my-backend
780+
781+
# Remove without confirmation
782+
ctx project:remove old-project --force
783+
784+
# Interactive selection
785+
ctx project:remove
786+
```

‎docs/mcp/projects.md‎

Lines changed: 118 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,12 @@ When the `-c` option is omitted, CTX will use the globally registered projects c
2929

3030
CTX provides several commands for managing your projects:
3131

32-
## Adding a Project (`project:add`)
32+
### Adding a Project (`project:add`)
3333

3434
Register a new project with the system:
3535

3636
```bash
37-
ctx project:add <path> [--name=<alias>] [--config-file=<path>] [--env-file=<path>]
37+
ctx project:add <path> [--name=<alias>] [--config-file=<path>] [--env-file=<path>] [--switch]
3838
```
3939

4040
**Example:**
@@ -60,8 +60,23 @@ ctx project:add . --name=my-backend --env-file=.env.dev
6060
- `--name`: Alias name for the project (optional)
6161
- `--config-file` or `-c`: Path to custom configuration file within the project (optional)
6262
- `--env-file` or `-e`: Path to .env file within the project (optional)
63+
- `--switch` or `-s`: Switch to this project after adding it (optional)
6364

64-
## Switching Between Projects (`project`)
65+
**Example output:**
66+
67+
```
68+
✓ Project added successfully
69+
70+
╭─● CURRENT ─────────────────────────────────────────────────────────╮
71+
│ /home/user/projects/my-backend
72+
│ Aliases: my-backend
73+
│ Added: Jan 18, 2025
74+
╰────────────────────────────────────────────────────────────────────╯
75+
76+
→ Set as current project (first project added)
77+
```
78+
79+
### Switching Between Projects (`project`)
6580

6681
Switch to a different registered project:
6782

@@ -93,6 +108,13 @@ or you can omit the argument to see a list of all registered projects:
93108
ctx project
94109
```
95110

111+
**Example output:**
112+
113+
```
114+
✓ Switched to project: /home/user/projects/my-backend
115+
Aliases: my-backend
116+
```
117+
96118
### Listing Projects (`project:list` or `projects`)
97119

98120
View all registered projects:
@@ -104,16 +126,99 @@ ctx project:list
104126
**Example output:**
105127

106128
```
107-
┌─────────────────────────────┬────────────────────┬──────────┬─────────────────┬─────────────────┬─────────┐
108-
│ Path │ Config File │ Env File │ Aliases │ Added │ Current │
109-
├─────────────────────────────┼────────────────────┼──────────┼─────────────────┼─────────────────┼─────────┤
110-
│ /home/user/projects/my-app │ │ │ my-app │ 2025-05-01 10:15│ │
111-
├─────────────────────────────┼────────────────────┼──────────┼─────────────────┼─────────────────┼─────────┤
112-
│ /home/user/projects/backend │ custom-context.yaml│ .env.dev │ my-backend, │ 2025-05-01 14:30│ active │
113-
│ │ │ │ backend │ │ │
114-
├─────────────────────────────┼────────────────────┼──────────┼─────────────────┼─────────────────┼─────────┤
115-
│ /home/user/projects/frontend│ │ │ my-ui │ 2025-05-02 09:45│ │
116-
└─────────────────────────────┴────────────────────┴──────────┴─────────────────┴─────────────────┴─────────┘
129+
╭─● CURRENT ─────────────────────────────────────────────────────────╮
130+
│ /home/user/projects/my-app
131+
│ Aliases: my-app
132+
│ Config: context.yaml
133+
│ Added: Jan 18, 2025
134+
╰────────────────────────────────────────────────────────────────────╯
135+
136+
╭─○──────────────────────────────────────────────────────────────────╮
137+
│ /home/user/projects/backend
138+
│ Aliases: my-backend, backend
139+
│ Config: custom-context.yaml
140+
│ Env: .env.dev
141+
│ Added: Jan 15, 2025
142+
╰────────────────────────────────────────────────────────────────────╯
143+
144+
╭─○──────────────────────────────────────────────────────────────────╮
145+
│ /home/user/projects/frontend
146+
│ Aliases: my-ui
147+
│ Added: Jan 10, 2025
148+
╰────────────────────────────────────────────────────────────────────╯
149+
150+
Commands:
151+
ctx project <path|alias> Switch to a project
152+
ctx project:add <path> Add a new project
153+
ctx project:remove <path|alias> Remove a project
154+
```
155+
156+
The output uses visual indicators:
157+
158+
- `●` (green) — Current active project
159+
- `○` (gray) — Other registered projects
160+
161+
### Removing a Project (`project:remove`)
162+
163+
Remove a project from the registry:
164+
165+
```bash
166+
ctx project:remove [<path_or_alias>] [--force] [--keep-aliases]
167+
```
168+
169+
**Arguments:**
170+
171+
- `path_or_alias`: Path or alias to the project (optional). If omitted, displays an interactive selection menu.
172+
173+
**Options:**
174+
175+
- `--force` or `-f`: Skip confirmation prompt
176+
- `--keep-aliases`: Keep aliases when removing project (not recommended)
177+
178+
**Example:**
179+
180+
Remove a project using its alias:
181+
182+
```bash
183+
ctx project:remove my-backend
184+
```
185+
186+
Remove without confirmation:
187+
188+
```bash
189+
ctx project:remove my-backend --force
190+
```
191+
192+
Interactive selection (when no argument provided):
193+
194+
```bash
195+
ctx project:remove
196+
```
197+
198+
**Example output:**
199+
200+
```
201+
╭─○──────────────────────────────────────────────────────────────────╮
202+
│ /home/user/projects/old-project
203+
│ Aliases: old-project
204+
│ Added: Jan 10, 2025
205+
╰────────────────────────────────────────────────────────────────────╯
206+
207+
Are you sure you want to remove this project? [y/N] y
208+
209+
✓ Project removed: /home/user/projects/old-project
210+
→ Aliases removed: old-project
211+
```
212+
213+
If you remove the current project, CTX will suggest switching to another:
214+
215+
```
216+
! This is the current project. It will be unset after removal.
217+
218+
✓ Project removed: /home/user/projects/my-app
219+
→ Aliases removed: my-app
220+
221+
→ Use ctx project my-backend to switch to another project
117222
```
118223

119224
## Configuring MCP Server for Project Switching

0 commit comments

Comments
 (0)