istok

CLI overview

Explore the Istok command-line interface for setup, inspection, troubleshooting, automation, and direct project management.

The Istok CLI gives you direct access to the same local project state that coding agents use through MCP.

For normal coding-agent workflows, you usually interact with Istok indirectly through your agent. The CLI remains useful for:

  • project setup;
  • inspecting Istok state;
  • troubleshooting agent workflows;
  • scripting and automation;
  • direct manual control when needed.

You do not need to reproduce an agent’s normal task and run workflow manually through CLI commands.

Commands

Run:

istok --help

to see the available top-level commands.

The main command groups are:

Command Purpose
istok init Initialize a repository as an Istok project.
istok mcp Start the local MCP server used by coding agents.
istok project Inspect and manage registered projects.
istok task Inspect and manage project tasks.
istok run Inspect runs, executions, artifacts, and validation.
istok context Inspect and manage durable project context.
istok index Inspect or rebuild the local repository index.
istok search Search indexed repository content.
istok graph Explore symbols and relationships in the code graph.
istok update Check for and install Istok updates.
istok completion Configure shell completion.
istok version Print version information.

Each command group has its own help:

istok task --help

Individual commands can be inspected in the same way:

istok task show --help

Project-aware commands

Most project operations are scoped to the repository you are currently working in.

For example:

cd my-project
istok task list

Istok resolves the current repository to its registered project and returns the tasks for that project.

The same model applies to commands such as:

istok context show
istok run list
istok index status
istok search "authentication timeout"

MCP uses the same project-oriented model with an additional boundary: each istok mcp process fixes its repository root when it starts and remains scoped to that project for its lifetime.

A global MCP configuration can therefore be reused across initialized repositories while each started MCP process operates on the repository it was launched for.

Inspect project state

The CLI is useful when you want to inspect what Istok currently knows without asking a coding agent.

Inspect the current project:

istok project show

List active tasks:

istok task list

Inspect durable project context:

istok context show

Inspect runs:

istok run list

Check the repository index:

istok index status

These commands are useful for understanding or troubleshooting agent workflows while keeping the normal workflow agent-driven.

Search the repository

Istok exposes its local repository retrieval through both the CLI and MCP.

Search indexed content:

istok search "authentication timeout"

Inspect a symbol:

istok graph symbol AuthService

Explore relationships around a symbol:

istok graph neighbors AuthService

Search and graph commands operate on the current Istok project.

Coding agents can use the same retrieval capabilities through MCP while working on tasks, so the CLI commands are primarily useful for inspection, troubleshooting, scripting, or direct exploration.

Repository freshness is handled by Istok as part of these workflows. You do not need to rebuild the index before normal searches or agent work.

See index, search and graph for the repository retrieval reference.

Human and JSON output

Istok commands use human-readable terminal output by default.

For programmatic use, supported commands can return structured JSON:

istok task list --json

JSON output uses versioned schemas so scripts and integrations can identify the contract they receive.

Use individual command help to see whether --json is available:

istok task list --help

See JSON output for the general structured-output conventions.

Data location

Istok stores durable local state in a SQLite database in the user data directory.

Most workflows do not require you to manage its path directly.

Commands that support a custom database can use:

--database PATH

or the environment variable:

ISTOK_DATABASE

Repository retrieval data and managed artifacts are stored separately from the main database.

See Configuration for the data locations and available overrides.

Shell completion

Istok can generate shell completion for Bash, Fish, and Zsh.

For example:

istok completion zsh

To print the initialization code directly:

istok completion zsh --code

The same pattern can be used with:

bash
fish
zsh

CLI and MCP

The CLI and MCP expose the same Istok project workflows for different kinds of interaction.

                         Istok
                        /     \
                       /       \
                    CLI         MCP
                     │           │
                     │           └── coding agents
                     │
                     ├── setup
                     ├── inspection
                     ├── troubleshooting
                     ├── automation
                     └── direct control

For normal development work:

You
 ↓
coding agent
 ↓
Istok MCP
 ↓
durable project state

The agent can find or create tasks, retrieve context, record progress, work through runs, preserve validation evidence, and leave state for later sessions.

The CLI gives you direct access to those same project concepts when you need it.

MCP process scope

A configured MCP client starts an istok mcp process for the repository in which it is working.

That process fixes two important pieces of identity at startup:

repository root
+
actor identity

The repository root determines which Istok project the process can access.

The actor identity determines which agent is performing operations through that process.

For example:

istok mcp \
  --actor-id codex \
  --actor-name "Codex"

See MCP for the full server and actor-identity reference.

Next

Continue with the project command reference for project management commands.