CLI & External Tools

Overview

The Thoughtful CLI brings your workspace into the terminal, enabling powerful integrations with AI agents, automation scripts, and developer workflows. It transforms Thoughtful into a "central nervous system" for your projects, where knowledge persists across sessions and can be accessed by both humans and AI alike.

Unlike local markdown files in a repository, Thoughtful is web-based with real-time collaboration, mobile access, and team chat. The CLI bridges this gap, letting you read and write to your knowledge base from any terminal environment.

Installation

Install the CLI globally using npm or bun:

Verify the installation:

Authentication

Before using the CLI, you need to authenticate with your Thoughtful account:

For non-interactive environments (CI/CD, scripts), you can provide credentials via flags:

Core Commands

Pages

Pages are the primary way to store and organize knowledge. The CLI provides full CRUD operations:

Search and Discovery

Find relevant content across your workspace:

Content Editing

Modify page content directly from the terminal:

Bulk Operations

Perform multiple actions efficiently:

Threads (AI Chat)

Interact with the AI assistant from your terminal:

Organizations and Workspaces

Manage multi-tenant access:

JSON Output

All commands support --json for machine-readable output, making it easy to pipe results to other tools:

Shell Completion

Set up tab completion for your shell:

Using with Claude Code

Thoughtful integrates seamlessly with Claude Code through a built-in skill. When Claude Code detects Thoughtful-related tasks, it automatically loads the skill to help manage your knowledge base.

The Thoughtful Skill

The skill teaches Claude Code how to:

• Check if the CLI is installed and authenticated
• Read and update pages during coding sessions
• Create new pages for discoveries and insights
• Establish a knowledge persistence loop

Enabling the Skill

The skill is automatically available when Claude Code detects Thoughtful usage. You can also reference it directly in your project's CLAUDE.md:

Recommended Page Structure

When setting up a project with AI agent integration, consider creating these foundational pages:

Agent Memory Loop

The real power of Thoughtful with AI agents comes from establishing a read-update cycle that ensures knowledge compounds across sessions:

• Start of session: Read pages relevant to the current task
• During work: Note insights worth persisting
• End of session: Update pages with new knowledge
• Create pages: For significant new topics or discoveries

This pattern prevents context loss between sessions and builds up a rich knowledge base over time.

Example Workflows

Capturing Meeting Notes

AI Research Session

Automated Reporting

Thoughtful as a Central Nervous System

When combined with AI agents, Thoughtful becomes more than just a note-taking app. It serves as a central nervous system for your projects:

• Persistent Memory: Information survives across sessions, so AI agents can build on previous work
• Shared Context: Multiple agents can read and write to the same knowledge base
• Human Collaboration: Non-technical team members can contribute via the web and mobile apps
• Cross-Tool Integration: The CLI connects Thoughtful to your existing workflows

This architecture enables AI agents to:

• Remember project context and decisions
• Learn from previous sessions
• Collaborate with humans asynchronously
• Build up institutional knowledge over time

Global Options

These options work with all commands:

Getting Help

Use the built-in help to explore commands: