Moose CLI Reference

Installation

bash -i <(curl -fsSL https://fiveonefour.com/install.sh) moose

Core Commands

Init

Initializes a new Moose project.

moose init <name> --template <template> [--location <location>] [--no-fail-already-exists]

• <name>: Name of your app or service
• <template>: Template to use for the project
• --location: Optional location for your app or service
• --no-fail-already-exists: Skip the directory existence check

List Templates

Lists available templates for project initialization.

moose template list

Build

Builds your Moose project.

moose build [--docker] [--amd64] [--arm64]

• --docker: Generate a Dockerfile and build Docker image(s)
• --amd64: Build for AMD64 architecture
• --arm64: Build for ARM64 architecture

Dev

Starts a local development environment with hot reload and automatic infrastructure management.

Prerequisites: Install project dependencies before running moose dev:

• TypeScript: npm install or pnpm install
• Python: pip install -r requirements.txt

moose dev [--mcp] [--no-infra] [--timestamps] [--timing] [--log-payloads]

• --mcp: Enable or disable the MCP (Model Context Protocol) server (default: true). The MCP server provides AI-assisted development tools at http://localhost:4000/mcp. See MCP Server documentation for details.
• --no-infra: Skip starting docker containers for infrastructure
• --timestamps: Show HH:MM:SS.mmm timestamps on all output lines (default: false)
• --timing: Show elapsed time for operations, e.g., "finished in 234ms" or "finished in 2s 300ms" (default: false)
• --log-payloads: Log payloads for debugging data flow (see PAYLOAD prefixed lines in moose logs --tail)

When debugging slow hot reloads, use --timing to identify which operation is the bottleneck; use --timestamps to correlate events across runs.

Running in Background: For AI assistants or when you need to run other commands in the same terminal:

nohup moose dev &

Example with timing flags:

# Basic dev mode
moose dev
 
# With timestamps for debugging
moose dev --timestamps
 
# With performance timing
moose dev --timing
 
# Both together for detailed monitoring
moose dev --timestamps --timing

Sample output with --timing:

Planning finished in 145msValidation finished in 23msExecution finished in 1s 200msPersist State finished in 45msOpenAPI Gen finished in 89ms

Sample output with --timestamps:

14:23:45.123 Planning started14:23:45.268 Planning completed14:23:45.291 Validation started14:23:45.314 Validation completed14:23:45.337 Execution started14:23:46.537 Execution completed

The development server includes:

• Hot reload for code changes
• Automatic Docker container management (ClickHouse, Redpanda, Temporal, Redis)
• Built-in MCP server for AI assistant integration
• Health monitoring and metrics endpoints

Prod

Starts Moose in production mode for cloud deployments.

moose prod

Check

Checks the project for non-runtime errors.

moose check [--write-infra-map]

Clean

Clears temporary data and stops development infrastructure.

moose clean

Seed (ClickHouse)

Seed your local ClickHouse from a remote ClickHouse instance.

moose seed clickhouse [--connection-string <CONNECTION_STRING>] [--table <name>] [--limit <n> | --all] [--order-by <clause>] [--report=true|false]

• --connection-string: Remote ClickHouse connection string. If omitted, the CLI uses MOOSE_SEED_CLICKHOUSE_URL.
• --table: Seed only the specified table (default: all Moose tables).
• --limit: Copy up to N rows (mutually exclusive with --all). Large limits are automatically batched.
• --all: Copy entire table(s) in batches (mutually exclusive with --limit).
• --order-by: ORDER BY clause for the query (e.g., --order-by 'timestamp DESC').
• --report: Report row counts after seeding (default: true). Counts shown for default database only; use --report=false to skip.

Connection String Format: The connection string must use ClickHouse native protocol:

# ClickHouse native protocol (secure connection)
clickhouse://username:password@host:9440/database

Important:

• The data transfer uses ClickHouse's native TCP protocol via remoteSecure() function. The remote ClickHouse server must have the native TCP port accessible (typically port 9440 for secure connections).
• Smart table matching: The command automatically validates tables between local and remote databases. Tables that don't exist on the remote are gracefully skipped with warnings.
• Use --table <name> to seed a specific table that exists in both local and remote databases.

User Experience:

• Progress indicator shows seeding status with spinner
• Tables that don't exist on remote are automatically skipped with clear warnings
• Final summary shows successful and skipped tables
• Clean, streamlined output focused on results

Notes:

• Seeding is batched automatically for large datasets; Ctrl+C finishes the current batch gracefully.
• Use env var fallback:

export MOOSE_SEED_CLICKHOUSE_URL='clickhouse://username:password@host:9440/database'

Truncate

Truncate tables or delete the last N rows from local ClickHouse tables.

moose truncate [TABLE[,TABLE...]] [--all] [--rows <n>]

• TABLE[,TABLE...]: One or more table names (comma-separated). Omit to use --all.
• --all: Apply to all non-view tables in the current database (mutually exclusive with listing tables).
• --rows <n>: Delete the last N rows per table; omit to remove all rows (TRUNCATE).

Notes:

• For --rows, the command uses the table ORDER BY when available; otherwise it falls back to a timestamp heuristic.

Monitoring Commands

Logs

View Moose logs.

moose logs [--tail] [--filter <search_string>]

• --tail: Follow logs in real-time
• --filter: Filter logs by specific string

Ps

View Moose processes.

moose ps

Ls

View Moose primitives & infrastructure.

moose ls [--limit <n>] [--version <version>] [--streaming] [--type <type>] [--name <name>] [--json]

• --limit: Limit output (default: 10)
• --version: View specific version
• --streaming: View streaming topics
• --type: Filter by infrastructure type (tables, streams, ingestion, sql_resource, consumption)
• --name: Filter by name
• --json: Output in JSON format

Metrics

View live metrics from your Moose application.

moose metrics

Peek

View data from a table or stream.

moose peek <name> [--limit <n>] [--file <path>] [-t|--table] [-s|--stream]

• <name>: Name of the table or stream to peek
• --limit: Number of rows to view (default: 5)
• --file: Output to a file
• -t, --table: View data from a table (default if neither flag specified)
• -s, --stream: View data from a stream/topic

Query

Execute arbitrary SQL queries against your ClickHouse database during development.

# Direct query
moose query "SELECT count(*) FROM users"
 
# From file
moose query -f queries/analysis.sql
 
# From stdin
cat query.sql | moose query
 
# With limit
moose query "SELECT * FROM events" --limit 100

• <query>: SQL query string to execute (optional if using --file or stdin)
• -f, --file <PATH>: Read query from file
• -l, --limit <NUM>: Maximum rows to return (default: 10000)

Requirements:

• Requires moose dev to be running
• Executes queries against your development ClickHouse instance

Output:

• Returns results as newline-delimited JSON
• One JSON object per row
• Row count summary at end

Formatting Queries for Code

Use the -c/--format-query flag to format SQL queries as code literals instead of executing them:

# Format as Python (raw string)
moose query -c python "SELECT * FROM users WHERE email REGEXP '[a-z]+'"
# Output:
# r"""
# SELECT * FROM users WHERE email REGEXP '[a-z]+'
# """
 
# Format as TypeScript (template literal)
moose query -c typescript "SELECT * FROM events"
# Output:
# `
# SELECT * FROM events
# `
 
# Works with file input
moose query -c python -f my_query.sql
 
# Prettify SQL before formatting (adds line breaks and indentation)
moose query -c python -p "SELECT id, name FROM users WHERE active = 1 ORDER BY name"
# Output:
# r"""
# SELECT id, name
# FROM users
#     WHERE active = 1
#     ORDER BY name
# """
 
# Use heredoc for multi-line SQL queries (no need to escape quotes)
moose query -c python -p <<EOF
SELECT
    b.id,
    b.name,
    b.email,
    COUNT(o.id) as order_count,
    SUM(o.total) as total_spent
FROM local.Bar b
LEFT JOIN local.Orders o ON b.id = o.user_id
WHERE b.status = 'active'
    AND o.created_at > '2024-01-01'
GROUP BY b.id, b.name, b.email
HAVING COUNT(o.id) > 5
ORDER BY total_spent DESC
LIMIT 50
EOF
 
# Supported languages: python (py), typescript (ts)
# Prettify flag: -p, --prettify (only works with --format-query)

Use case: Iterate on SQL queries in the CLI, then format and paste into your application code without manual escaping. Use --prettify to clean up messy one-line queries.

Generation Commands

Generate Dockerfile

Generate a Dockerfile for your project without building Docker images.

moose generate dockerfile

Requires custom_dockerfile = true in moose.config.toml. The generated Dockerfile is placed at dockerfile_path (default: ./Dockerfile) and can be customized for your deployment needs.

Generate Hash Token

Generate authentication tokens for API access.

moose generate hash-token

Generates both a plain-text Bearer token and its corresponding hashed version for authentication.

Generate Migration Plan (OLAP)

Create an ordered ClickHouse DDL plan by comparing a remote instance with your local code.

moose generate migration --url https://<remote-env> --token <api-token> --save

• Writes ./migrations/plan.yaml and snapshots remote_state.json and local_infra_map.json

• Omit --save to output to stdout without writing files

• Requires these feature flags in moose.config.toml:

  Copy code

  moose.config.toml

  [features]olap = trueddl_plan = true

DB Pull (External Tables)

Refresh EXTERNALLY_MANAGED table definitions from a remote ClickHouse instance.

moose db pull --clickhouse-url <URL> [--file-path <OUTPUT_PATH>]

• --clickhouse-url: ClickHouse URL (e.g., clickhouse://user:pass@host:port/database or https://user:pass@host:port/database). Native clickhouse:// is auto-converted to HTTP(S). Include ?database= or the CLI will query the current database.
• --file-path: Optional override for the generated external models file (defaults to app/externalModels.ts or app/external_models.py).

Notes:

• Only tables marked EXTERNALLY_MANAGED in your code are refreshed.
• The command writes a single external models file and overwrites the file on each run.
• See the full guide: DB Pull

Kafka

Pull external topics and schemas

Discover topics from a Kafka/Redpanda cluster and optionally fetch JSON Schemas from Schema Registry to emit typed external models.

moose kafka pull <bootstrap> [--path <PATH>] [--include <glob>] [--exclude <glob>] [--schema-registry <URL>]

• <bootstrap>: Kafka bootstrap servers, e.g. localhost:19092
• --path: Output directory for generated files. Defaults to app/external-topics (TS) or app/external_topics (Python).
• --include: Include pattern (glob). Default: *
• --exclude: Exclude pattern (glob). Default: {__consumer_offsets,_schemas}
• --schema-registry: Base URL for Schema Registry, e.g. http://localhost:8081

Notes:

• JSON Schema is supported initially; Avro/Protobuf planned.
• Generated files will be overwritten on subsequent runs.

Workflow Management

Workflow

moose workflow <command> [options]

Available workflow commands:

• init <name> [--tasks <task-list>] [--task <task>...]: Initialize a new workflow
• run <name> [--input <json>]: Run a workflow
• resume <name> --from <task>: Resume a workflow from a specific task
• list [--json]: List registered workflows
• history [--status <status>] [--limit <n>] [--json]: Show workflow history
• terminate <name>: Terminate a workflow
• pause <name>: Pause a workflow
• unpause <name>: Unpause a workflow
• status <name> [--id <run-id>] [--verbose] [--json]: Get workflow status

Help & Support Commands

Feedback

Send feedback, report bugs, or join the Moose community.

moose feedback [message] [--email <email>] [--bug] [--community]

Send feedback:

# Send feedback (will prompt for optional email)
moose feedback "loving the DX!"
 
# Include email for follow-up
moose feedback "great tool!" --email you@example.com

Report a bug:

# Open GitHub Issues with system info pre-filled
moose feedback --bug "crash on startup"
 
# Bug report without description
moose feedback --bug

Join the community:

# Open Moose Slack community in your browser
moose feedback --community

Options:

• [message]: Your feedback message (required for feedback and bug reports)
• --email <email>: Optional email address for follow-up on feedback
• --bug: Open GitHub Issues for bug reporting with environment details
• --community: Open Moose Slack community invite

Notes:

• Feedback requires telemetry to be enabled
• Email is optional and only used if you want the team to follow up
• Bug reports include CLI version, OS, architecture, and log file paths
• If email is not provided via flag, you'll be prompted interactively (optional)

Planning and Deployment

Plan

Display infrastructure changes for the next production deployment.

For Moose Server deployments:

moose plan [--url <url>] [--token <token>]

• --url: Remote Moose instance URL (default: http://localhost:4000)
• --token: API token for authentication

For Serverless deployments:

moose plan --clickhouse-url <url>

• --clickhouse-url: ClickHouse connection URL (e.g., clickhouse://user:pass@host:port/database)

Refresh

Integrate matching tables from a remote instance into the local project.

moose refresh [--url <url>] [--token <token>]

• --url: Remote Moose instance URL (default: http://localhost:4000)
• --token: API token for authentication

Documentation & Feedback

Docs

Fetch and display LLM-optimized documentation in the terminal.

moose docs [<slug>] [-l <LANG>] [--raw] [--expand] [--web]

• <slug>: Documentation page slug (e.g., moosestack/olap). Omit to show the table of contents. Slugs are case-insensitive.
• -l, --lang <LANG>: Language for documentation: typescript (ts) or python (py). Auto-detected from your project language or saved preference.
• --raw: Output raw content without formatting (for piping to other tools)
• --expand: Show full expanded tree with all leaf pages and guide section headings
• --web: Open documentation page in your web browser instead of printing

Subcommands

• moose docs browse [--web]: Interactively browse and select a documentation page with a hierarchical drill-down picker
• moose docs search <query>: Search documentation by title or description

Guide Section Navigation

Guide pages are large and support section navigation with #anchor syntax:

moose docs guides/chat-in-your-app#overview
moose docs guides/chat-in-your-app#setup

If the section is not found, available sections are listed. When using browse on a guide page, a secondary section picker is shown.

Use with AI Clients

The --raw flag outputs unformatted markdown, making it easy to pipe documentation to AI clients for processing:

moose docs --raw guides/chat-in-your-app#setup | claude "do this step, ask me any questions you need to execute"

This pattern works with any AI client that accepts stdin, allowing you to get AI assistance on specific documentation sections.

Feedback

Submit feedback, report bugs, or join the community.

moose feedback [MESSAGE] [--bug] [--community]

• [MESSAGE]: Feedback message (e.g., moose feedback "loving the DX!")
• --bug: Report a bug (opens GitHub Issues with system info and log paths)
• --community: Join the Moose community on Slack

This reference reflects the current state of the Moose CLI based on the source code in the framework-cli directory. The commands are organized by their primary functions and include all available options and flags.