istok project

istok project shows and manages registered projects. For what a project is and where its data lives, see Projects.

Commands

Without a selector, commands use the project that contains the current directory; with nested projects, the closest root wins.

Selectors

SELECTOR can be:

• the project ID;
• an unambiguous ID prefix;
• the project name.

istok project show acme-api
istok project show 01a00b35

Names do not have to be unique. If a selector matches more than one project, Istok reports it as ambiguous; use the ID or a longer prefix.

Register a project: istok init

cd ~/work/acme-api
istok init

This registers the directory and builds the first code index. Running it again in a directory that is already a project root returns the existing project. Agents do the same with the MCP tool project_init.

A project can be registered inside another project’s directory, for example an app inside a monorepo:

cd ~/work/platform
istok init

cd ~/work/platform/apps/web
istok init

Both projects stay independent. Commands and MCP servers started inside apps/web use web; everywhere else in ~/work/platform they use platform. Two active projects cannot have exactly the same root.

Show a project

istok project show
istok project show acme-api

Shows the project’s identity, state, and repository binding.

List projects

istok project list

The output shows each project’s name, state, and full repository root path. Deleted projects are hidden; include them to find one to restore:

istok project list --deleted

Rename a project

istok project rename new-name
istok project rename new-name --project acme-api

Changes only the Istok name, not the directory or any state.

Rebind a project

If a repository moves, rebind the existing project instead of registering a new one:

mv ~/work/acme-api ~/projects/acme-api
cd ~/projects/acme-api
istok project rebind acme-api

Without PATH, the current directory is used. You can also pass it explicitly:

istok project rebind acme-api /path/to/repository

Tasks, context, runs, and all other state stay with the project.

The same command binds a project imported from another device, which has no folder on this device yet. See Moving projects to another device.

Delete a project

istok project delete
istok project delete --project acme-api

Istok asks for confirmation; --yes skips it, and is required with --json so the command does not wait for input.

Deleting does not touch the repository or its files. The project is kept in a recoverable state with its tasks, runs, and history, and its directory is released so another project can use it. You can also delete a project from the web UI; the result is the same.

Restore a project

istok project restore acme-api
istok project restore acme-api /path/to/repository

Without a path, Istok reuses the project’s previous root. If that directory no longer exists, the command fails and asks for a path. Restoring fails if another active project already uses the directory.

Help

istok project show --help
istok project rebind --help
istok project restore --help