Deprecate shell command and hide from help output

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Deprecated
+
+- The `shell` command (`mcpc shell @<session>` and `mcpc @<session> shell`) is deprecated and will be removed in a future release. It is now hidden from `--help` output and prints a deprecation warning when invoked
+
 ## [0.3.0] - 2026-05-20
 
 ### Added

README.md

@@ -127,6 +127,53 @@ mcpc @fs tools-list
 <!-- AUTO-GENERATED: mcpc --help -->
 
 ```
+Usage: mcpc [<@session>] [<command>] [options]
+
+Universal command-line client for the Model Context Protocol (MCP).
+
+Commands:
+  connect <server> [@session]  Connect to an MCP server and start a new named @session
+  close <@session>             Close a session
+  restart <@session>           Restart a session (losing all state)
+  login <server>               Interactively login to a server using OAuth and save profile
+  logout <server>              Delete an OAuth profile for a server
+  clean [resources...]         Clean up mcpc data (sessions, profiles, logs, all)
+  grep <pattern>               Search tools and instructions across all active sessions
+  x402 [subcommand] [args...]  Configure an x402 payment wallet (EXPERIMENTAL)
+  help [command] [subcommand]  Show help for a specific command
+
+Options:
+  --json                       Output in JSON format for scripting
+  --verbose                    Enable debug logging
+  --profile <name>             OAuth profile for the server ("default" if not provided)
+  --timeout <seconds>          Request timeout in seconds (default: 300)
+  --max-chars <n>              Truncate output to n characters (ignored in --json mode)
+  --insecure                   Skip TLS certificate verification (for self-signed certs)
+  -v, --version                Output the version number
+  -h, --help                   Display help
+
+MCP session commands (after connecting):
+  <@session>                   Show MCP server info, capabilities, and tools overview
+  <@session> grep <pattern>    Search tools and instructions
+  <@session> tools-list        List all server tools
+  <@session> tools-get <name>  Get tool details and schema
+  <@session> tools-call <name> [arg:=val ... | <json> | <stdin]
+  <@session> prompts-list
+  <@session> prompts-get <name> [arg:=val ... | <json> | <stdin]
+  <@session> resources-list
+  <@session> resources-read <uri>
+  <@session> resources-subscribe <uri>
+  <@session> resources-unsubscribe <uri>
+  <@session> resources-templates-list
+  <@session> tasks-list
+  <@session> tasks-get <taskId>
+  <@session> tasks-result <taskId>
+  <@session> tasks-cancel <taskId>
+  <@session> logging-set-level <level>
+  <@session> ping
+
+Run "mcpc" without arguments to show active sessions and OAuth profiles.
+Run "mcpc --json" to get the same data as `{ sessions: [...], profiles: [...] }`.
 ```
 
 ### General actions

src/cli/commands/sessions.ts

@@ -1538,6 +1538,9 @@ async function maybeConnectApify(
  * Open an interactive shell for a target
  */
 export async function openShell(target: string): Promise<void> {
+  console.error(
+    formatWarning('The "shell" command is deprecated and will be removed in a future release.')
+  );
   // Import shell dynamically to avoid circular dependencies
   const { startShell } = await import('../shell.js');
   await startShell(target);

src/cli/index.ts

@@ -591,11 +591,11 @@ ${jsonHelp(
       await sessions.restartSession(sessionName, getOptionsFromCommand(command));
     });
 
-  // shell command: mcpc shell @<session>
+  // shell command: mcpc shell @<session> (deprecated, hidden from help)
   program
-    .command('shell [@session]')
+    .command('shell [@session]', { hidden: true })
     .usage('<@session>')
-    .description('Open interactive shell for a session')
+    .description('Open interactive shell for a session (deprecated)')
     .action(async (sessionName) => {
       if (!sessionName) {
         throw new ClientError('Missing required argument: @session\n\nExample: mcpc shell @myapp');
@@ -882,10 +882,10 @@ function registerSessionCommands(program: Command, session: string): void {
       command.parent.outputHelp();
     });
 
-  // Shell command
+  // Shell command (deprecated, hidden from help)
   program
-    .command('shell')
-    .description('Launch interactive MCP shell.')
+    .command('shell', { hidden: true })
+    .description('Launch interactive MCP shell (deprecated).')
     .action(async () => {
       await sessions.openShell(session);
     });

src/cli/output.ts

@@ -1445,7 +1445,6 @@ export function formatServerDetails(
   }
 
   // Commands
-  lines.push(chalk.bold('Available commands:'));
   const commands: string[] = [];
 
   if (capabilities?.tools) {
@@ -1479,10 +1478,11 @@ export function formatServerDetails(
     commands.push(`${bullet} ${bt}mcpc ${target} logging-set-level <lvl>${bt}`);
   }
 
-  commands.push(`${bullet} ${bt}mcpc ${target} shell${bt}`);
-
-  lines.push(commands.join('\n'));
-  lines.push('');
+  if (commands.length > 0) {
+    lines.push(chalk.bold('Available commands:'));
+    lines.push(commands.join('\n'));
+    lines.push('');
+  }
 
   // Debugging hint: bridge log file path (only shown for sessions, i.e. @name targets)
   if (target.startsWith('@')) {

test/unit/cli/output.test.ts

@@ -1048,7 +1048,8 @@ describe('formatServerDetails', () => {
     expect(output).toContain('mcpc @test resources-read');
     expect(output).toContain('mcpc @test prompts-list');
     expect(output).toContain('mcpc @test logging-set-level');
-    expect(output).toContain('mcpc @test shell');
+    // shell is deprecated and no longer listed
+    expect(output).not.toContain('mcpc @test shell');
 
     // Should contain instructions in code block
     expect(output).toContain('Instructions:');
@@ -1073,9 +1074,8 @@ describe('formatServerDetails', () => {
     expect(output).toContain('Capabilities:');
     expect(output).toContain('(none)');
 
-    // Should only show shell command
-    expect(output).toContain('Available commands:');
-    expect(output).toContain('mcpc https://example.com shell');
+    // With no capabilities, no commands are listed
+    expect(output).not.toContain('Available commands:');
     expect(output).not.toContain('tools-list');
     expect(output).not.toContain('resources-list');
     expect(output).not.toContain('prompts-list');