CLI overview — Istok

The istok command gives you direct access to the same local state your agent uses through MCP. Use it to set things up, look at what agents recorded, troubleshoot, and script. You do not need it for the normal agent workflow.

Commands

Command	Purpose
`istok init`	Register the current directory (or a given path) as a project.
`istok mcp`	Run the MCP server used by coding agents. See MCP tools.
`istok ui`	Open the local web UI or manage it as a service. See `istok ui`.
`istok project`	Show and manage registered projects. See `istok project`.
`istok task`	Inspect and operate tasks. See `istok task`.
`istok run`	Runs, executions, artifacts, and validation. See `istok run`.
`istok context`	Saved project context. See `istok context`.
`istok knowledge`	Project knowledge. See `istok knowledge`.
`istok index`	Inspect or rebuild the code index.
`istok search`	Search the code index.
`istok graph`	Explore symbols and relationships. See index, search and graph.
`istok export`	Export projects to a file for another device. See Moving projects to another device.
`istok import`	Import projects exported on another device.
`istok update`	Check for and install a new release.
`istok completion`	Set up shell completion.
`istok version`	Print version information.

Every command and subcommand has its own help, which is the authoritative list of flags for your installed version:

istok --help
istok task --help
istok task show --help

The current project

Most commands work on the project that contains your current directory:

cd ~/work/acme-api
istok task list

If projects are nested, the closest one wins: inside apps/web of a monorepo, commands use the apps/web project when one is registered there. See Projects.

istok mcp follows the same rule, with one difference: each MCP server process fixes its project root and its actor identity when it starts and keeps them for its lifetime. A single global MCP configuration therefore works across all registered repositories. See MCP tools.

A quick look at the state

istok project show       # the current project
istok task list          # open tasks
istok run list           # runs in this project
istok context show       # saved context as Markdown
istok index status       # code index health
istok search "order not found"
istok graph symbol OrderService
istok graph neighbors OrderService

You do not need to rebuild the index before searching; freshness is checked automatically.

For browsing rather than querying, istok ui shows the same state across all projects. See the Web UI guide.

JSON output

Output is human-readable by default. Supported commands accept --json and return a versioned response for scripts:

istok task list --json

Each command’s --help shows whether --json is available. See JSON output.

Database

Istok keeps its state in a local SQLite database in your user data directory. On Linux and macOS, the file is created with 0600 permissions and its default directory with 0700, so other users on the machine cannot read it.

Commands that support a custom database accept --database PATH or the ISTOK_DATABASE environment variable. The code index and managed artifacts are stored separately from the database. See Configuration.

Shell completion

Istok generates completion for Bash, Fish, and Zsh:

istok completion zsh

To print the initialization code directly:

istok completion zsh --code

Replace zsh with bash or fish as needed.