Maitento Shell Reference Guide

The Maitento Shell is a powerful command-line interface providing interactive and programmatic access to the Maitento platform. This comprehensive guide covers all aspects of the shell, from architecture to command reference.

Table of Contents

1. Overview
2. Getting Started
3. Architecture
4. File System Commands
5. Virtual File System Management
6. Process Management
7. Namespace Management
8. Resource Management Commands
9. Application Commands
10. Interaction Commands
11. Capsule Commands
12. Automated Action Commands
13. Build and Deployment
14. Configuration Commands
15. Common Workflows
16. Exit Codes Reference

Overview

The Maitento Shell is a plugin-based CLI system that supports:

• Interactive REPL mode: For exploratory work and debugging
• One-shot command execution: For scripting and automation
• Extensible plugin architecture: For custom command sets
• Virtual file system integration: For seamless remote file operations
• Multi-namespace support: For environment isolation

Key Features

• 110+ built-in commands organized by functional area
• Universal --namespace or -ns parameter for namespace scoping
• Structured output suitable for both humans and machines
• Real-time WebSocket notifications
• Comprehensive file system operations on both local and virtual filesystems

Getting Started

Initial Setup

1. Set the API URL

api-url-set https://your-maitento-instance.com

2. Authenticate

api-login

The shell supports multiple authentication types. Follow the prompts to complete authentication.

3. Set your default namespace

default-namespace-set production

4. Verify configuration

config-get

Configuration File

Shell configuration is stored at ~/.maitento/settings.json with the following properties:

API Management Commands

Verbose Logging

Architecture

Core Components

IShell Interface

• Main entry point for shell operations
• Properties: Context, IsAcceptingInput
• Methods: Execute(), Input(), Initialise()
• Events: OutputStandard, OutputError, OutputTrace

IShellContext

• Provides context to commands
• ClientHelper - API client access
• FileSystem - Virtual and local file system
• Configuration - Shell configuration

ShellCommandBase

• Abstract base class for all commands
• Declarative command definition via DefineCommand()
• Parameter system with validation
• Output methods: PrintLine(), PrintError(), PrintWarn()
• Structured results via AddResult()

Plugin System

The shell uses a plugin architecture for extensibility:

interface IShellPlugin {
    Task Initialise(IShellContext context);
    IShellCommand[] Commands { get; }
}

CoreShellPlugin auto-discovers IShellCommand implementations through reflection with lazy instantiation.

Output Streams

File System Commands

The shell provides comprehensive file system operations supporting both local and virtual file systems.

Path Format

VFS paths follow this format:

/vfs/<name>@<namespace>/<relative-path>

Examples:

/vfs/myfs@default/src/main.cs
/vfs/project@production/config/settings.json

cd - Change Directory

Changes the current working directory.

Syntax:

cd [path]

Examples:

cd /vfs/myfs@default/src    # Change to VFS directory
cd ..                        # Navigate to parent
cd /                         # Navigate to root

pwd - Print Working Directory

Displays the current working directory.

Syntax:

pwd

ls - List Files and Directories

Lists files and directories at the specified path.

Syntax:

ls [path]

Examples:

ls                               # List current directory
ls /vfs/myfs@default/src        # List specific directory
ls ..                            # List parent directory

cat - Read File Contents

Reads and displays the contents of a file as text.

Syntax:

cat <path> [--lines] [--number]

Parameters:

Examples:

cat /vfs/myfs@default/config.json
cat /vfs/myfs@default/src/main.cs --number

write - Write to File

Writes text content to a file in VFS.

Syntax:

write <path> --content <text> [--lines] [--append]

Parameters:

Examples:

write /vfs/myfs@default/readme.txt --content "Hello, World!"
write /vfs/myfs@default/log.txt --content "New entry" --append

edit - Edit File Contents

Edits a file with find/replace, line range edits, inserts, and deletes.

Syntax:

edit <path> [options]

Operations:

Find/Replace:

edit /vfs/myfs@default/config.cs --find "localhost" --replace "production.server.com"
edit /vfs/myfs@default/app.cs --find "var " --replace "const " --replace-all

Line Range Edit:

edit /vfs/myfs@default/main.cs --start-line 10 --end-line 15 --content "// New content"

Insert After:

edit /vfs/myfs@default/file.cs --insert-after 0 --content "// Copyright header"
edit /vfs/myfs@default/file.cs --insert-after 5 --content "    private int field;"

Delete Lines:

edit /vfs/myfs@default/old.cs --delete-lines "5,10,15,20"

mkdir - Create Directory

Creates a directory and any necessary parent directories.

Syntax:

mkdir <path>

Examples:

mkdir /vfs/myfs@default/new-folder
mkdir /vfs/myfs@default/src/components/ui

rm - Delete File or Directory

Deletes a file or directory recursively.

Syntax:

rm <path>

Examples:

rm /vfs/myfs@default/temp.txt
rm /vfs/myfs@default/old-folder

cp - Copy File or Directory

Copies a file or directory to a new location.

Syntax:

cp <source> <destination>

Examples:

cp /vfs/myfs@default/config.json /vfs/myfs@default/config.backup.json
cp /vfs/myfs@default/src /vfs/myfs@default/src-backup

mv - Move/Rename File or Directory

Moves or renames a file or directory.

Syntax:

mv <source> <destination>

Examples:

mv /vfs/myfs@default/old-name.cs /vfs/myfs@default/new-name.cs
mv /vfs/myfs@default/temp/file.txt /vfs/myfs@default/archive/file.txt

find - Search for Files

Finds files using glob patterns with optional content search.

Syntax:

find <path> [--pattern <glob>] [--grep <search>] [options]

Parameters:

Examples:

find /vfs/myfs@default/src --pattern "**/*.cs"
find /vfs/myfs@default/src --pattern "**/*.tsx" --grep "useState"
find /vfs/myfs@default --grep "TODO|FIXME" --regex --ignore-case
find /vfs/myfs@default/src --type directory

tree - Display Directory Tree

Displays a recursive directory tree structure.

Syntax:

tree <path> [options]

Parameters:

Examples:

tree /vfs/myfs@default/src
tree /vfs/myfs@default/src --max-depth 2
tree /vfs/myfs@default/src --files false
tree /vfs/myfs@default/src --pattern "*.ts"

Output:

src/
  components/
    Button.tsx
    Header.tsx
  utils/
    helpers.ts
  index.ts

3 directories, 4 files

exists - Check File/Directory Exists

Checks if a file or directory exists.

Syntax:

exists <path> [--directory]

Return Codes:

• 0: Exists
• 1: Does not exist
• -1: Error

Examples:

exists /vfs/myfs@default/config.json
exists /vfs/myfs@default/src --directory

batch-read - Read Multiple Files

Reads multiple files in a single operation.

Syntax:

batch-read <vfs> --paths <comma-separated-paths> [--max-lines <n>]

Examples:

batch-read myfs@default --paths "/src/main.cs,/src/config.json,/readme.md"
batch-read myfs@default --paths "/src/large-file.cs" --max-lines 100

Virtual File System Management

vfs-list - List Virtual File Systems

Lists all VFS in a namespace.

Syntax:

vfs-list [--namespace <namespace>]

Output Columns: Id, Name, Namespace, Mounts, Status

vfs-get - Get VFS Details

Gets details of a specific VFS.

Syntax:

vfs-get <name> [--namespace <namespace>]

vfs-create - Create Virtual File System

Creates a new VFS.

Syntax:

vfs-create <name> [--namespace <namespace>]

Examples:

vfs-create myfs
vfs-create myfs --namespace production

vfs-destroy - Destroy Virtual File System

Permanently deletes a VFS and all its contents.

Syntax:

vfs-destroy <name> [--namespace <namespace>]

Warning: This action is permanent and cannot be undone.

Process Management

ps - List Running Processes

Lists all alive processes (apps, interactions, capsules, code generation).

Syntax:

ps [--namespace <namespace>]

kill - Terminate Process

Terminates a running process.

Syntax:

kill -t <type> -i <id>

Process Types: App, Interaction, CodeGeneration, Capsule

Examples:

kill -t App -i 550e8400-e29b-41d4-a716-446655440000
kill -t Interaction -i 123e4567-e89b-12d3-a456-426614174000

notifications - Subscribe to Real-time Updates

Subscribes to WebSocket notifications.

Syntax:

notifications [<type>] [--filter <id>]

Notification Types:

• all - All notification types
• code-gen - Code generation updates
• app-process - App process updates
• interaction-process - Interaction updates
• interaction-process-stream - Interaction streaming
• capsule-process - Capsule updates
• file - File ingestion updates

Examples:

notifications
notifications code-gen
notifications app-process --filter 550e8400-e29b-41d4-a716-446655440000

Press Ctrl+C to disconnect.

Namespace Management

namespace-create

Creates a new namespace.

Syntax:

namespace-create <name>

namespace-get

Gets details of a namespace.

Syntax:

namespace-get <name>

namespace-list

Lists all namespaces.

Syntax:

namespace-list

namespace-update

Renames a namespace.

Syntax:

namespace-update <name> --new-name <new-name>

default-namespace-get / ns-get

Gets the current default namespace.

Syntax:

default-namespace-get
ns-get

default-namespace-set / ns-set

Sets the default namespace.

Syntax:

default-namespace-set <namespace>
ns-set <namespace>

Resource Management Commands

Secrets

Manage secure credential storage.

Note: Use --unmask with secret-get to reveal the actual value.

API Keys

Manage API keys for programmatic access.

Important: The API key secret is only shown once upon creation.

Agents

Manage AI agents.

AI Models

Connectors

External Operations

Partitions

Manage file partitions for RAG and document organization.

Files (Partition Files)

Manage files within partitions.

Supported File Types:

• Text: .txt, .md, .csv, .html, .css, .js, .json, .xml
• Documents: .pdf, .doc, .docx, .xls, .xlsx
• Images: .png, .jpg, .jpeg, .gif, .svg
• Archives: .zip

Webhooks

Webhook Types: AppProcess, CodeGenerationProcess, IngestedFile, InteractionProcess

Application Commands

Examples:

app-list
app-run my-app --input-param "value"
app-attach 550e8400-e29b-41d4-a716-446655440000
app-ps --namespace production

Interaction Commands

Examples:

interaction-run my-interaction --prompt "Process this data"
interaction-attach 550e8400-e29b-41d4-a716-446655440000
interaction-vote-yes 550e8400-e29b-41d4-a716-446655440000

Capsule Commands

Examples:

capsule-start my-capsule
capsule-exec <process-id> --command "ls" --args "-la"
capsule-mount-vfs <process-id> --vfs-id <id> --mount-name workspace

Automated Action Commands

Build and Deployment

build

Validates a Maitento project without deploying.

Syntax:

build <path> [--namespace <namespace>]

Project Structure:

project/
  json/           # JSON resource files (*.json)
  prompts/        # Prompt files (*.md)
  connectors/
    open-api/     # OpenAPI connector definitions (*.mtr)
  external-operations/
    open-api/     # External operation definitions (*.mtr)
  agents/         # Agent definitions (*.mtr)
  capsules/       # Capsule definitions (*.mtr)
  interactions/
    one-shot/     # One-shot interactions (*.mtr)
    round-robin/  # Round-robin interactions (*.mtr)
  apps/           # Application folders (*.mtc, *.mtr)

deploy

Builds and deploys a project to the server.

Syntax:

deploy <path> [--namespace <namespace>]

Examples:

build ./my-project
deploy ./my-project --namespace production

Code Generation Commands

Options for codegen-start/run:

• --git-ssh-key: Base64 encoded SSH key
• --git-http-credentials: HTTP credentials (username:password)
• --code-guidelines: Code guidelines for generation
• --generate-diff: Generate diff on completion

Examples:

codegen-start "https://github.com/user/repo.git" main feature/new-feature \
  '[{"step":"Add unit tests"}]' \
  --git-http-credentials "user:token" \
  --generate-diff true

codegen-attach 550e8400-e29b-41d4-a716-446655440000

Configuration Commands

Common Workflows

Initial Setup Workflow

# 1. Configure API endpoint
api-url-set https://maitento.example.com

# 2. Authenticate
api-login

# 3. Set default namespace
default-namespace-set production

# 4. Verify setup
config-get
namespace-list

Project Development Workflow

# 1. Create a VFS for your project
vfs-create my-project

# 2. Navigate to the VFS
cd /vfs/my-project@default

# 3. Create directory structure
mkdir src
mkdir tests

# 4. Create and edit files
write src/main.cs --content "using System;\n\nclass Program { }"
edit src/main.cs --find "{ }" --replace "{\n    static void Main() { }\n}"

# 5. Explore the structure
tree /vfs/my-project@default

Deployment Workflow

# 1. Validate the project
build ./my-maitento-project

# 2. Deploy to staging
deploy ./my-maitento-project --namespace staging

# 3. Test in staging
app-run my-app --namespace staging

# 4. Deploy to production
deploy ./my-maitento-project --namespace production

Running and Monitoring Applications

# 1. List available apps
app-list

# 2. Run an app interactively
app-run my-app --param1 "value1"

# 3. Or start and attach separately
app-start my-app --param1 "value1"
app-ps  # Get the process ID
app-attach <process-id>

# 4. Monitor with notifications
notifications app-process --filter <process-id>

Interaction Workflow

# 1. Start an interaction
interaction-start my-interaction --prompt "Analyze this data"

# 2. Check process list
interaction-ps

# 3. Attach to monitor
interaction-attach <process-id>

# 4. Add additional messages if needed
interaction-add-message <process-id> --message "Also check for errors"

# 5. Approve or reject results
interaction-vote-yes <process-id>
# or
interaction-vote-no <process-id> --reason "Results were incomplete"

Capsule Development Workflow

# 1. Start a capsule
capsule-start dev-capsule

# 2. Get the process ID
capsule-ps

# 3. Mount a VFS for code access
capsule-mount-vfs <process-id> --vfs-id <vfs-id> --mount-name code

# 4. Mount secrets for credentials
capsule-mount-secret <process-id> --secret-name api-key --mount-name credentials

# 5. Execute commands
capsule-exec <process-id> --command "npm" --args "install"
capsule-exec <process-id> --command "npm" --args "test"

# 6. Terminate when done
capsule-terminate <process-id>

File Search and Analysis

# 1. Find all TypeScript files
find /vfs/myfs@default/src --pattern "**/*.ts"

# 2. Search for specific content
find /vfs/myfs@default/src --pattern "**/*.ts" --grep "useState" --context 3

# 3. Find TODO comments
find /vfs/myfs@default --grep "TODO|FIXME" --regex --ignore-case

# 4. Read multiple related files
batch-read myfs@default --paths "/src/index.ts,/src/types.ts,/src/utils.ts"

Secret Management Workflow

# 1. Create secrets
secret-create db-password --value "super-secret"
secret-create api-key --value "sk-abc123"

# 2. List secrets (values masked)
secret-list

# 3. Retrieve a secret value
secret-get api-key --unmask

# 4. Update a secret
secret-update api-key --value "sk-new-key"

# 5. Clean up old secrets
secret-delete old-unused-key

Exit Codes Reference

Command Summary by Category

See Also

• Maitento API Reference
• SDK Reference
• Capsule Development Guide
• Interaction Development Guide