Skip to main content

Getting Started with CIAK

This guide walks you through the full workflow:

  1. Download and install the CIAK CLI and MCP server binaries.
  2. Initialize a project and run your first scan.
  3. Sync knowledge and (optionally) cloud data.
  4. Configure the MCP server in your IDE.
  5. Use CIAK via MCP from compatible AI tools.

This document assumes you are comfortable with a terminal and can run downloaded binaries on your machine.

1. Install CIAK from a release​

Go to the official CIAK download page or releases page and download the archive for your platform.

For example (Linux-style workflow):

wget https://your-download-url/ciak-vX.Y.Z-linux-x64.tar.gz
tar -xzf ciak-vX.Y.Z-linux-x64.tar.gz
cd linux-x64
sudo mv ciak ciak-mcp-server /usr/local/bin/

On Windows, download the ZIP, extract it, and add the folder containing ciak.exe and ciak-mcp-server.exe to your PATH.

After installation, verify:

ciak --version
ciak-mcp-server --version

2. (Optional) Activate your license​

Some features (vector search, cloud sync, multi‑project) and SaaS integration may require an active license.

Activate your license once on the machine:

ciak license activate XXXX-XXXX-XXXX-XXXX
ciak license status --detailed

This creates a license file at ~/.ciak/license used by cloud sync and other components.

For more details, see the license keyword reference.

3. Initialize and scan your first project​

From inside your code project directory:

# 1. Initialize CIAK project metadata
ciak init

# 2. Run a first scan with embeddings
ciak scan --embeddings

What this does:

  • Creates a .ciak/ folder in your project.
  • Builds a local database (.ciak/database.db) with files, symbols, and relationships.
  • Generates optional embeddings for semantic search if --embeddings is used.

You can confirm the scan worked by running:

ciak search "authentication" --with-context

4. Sync knowledge into CIAK​

CIAK supports a knowledge base with technical terms, synonyms, and acronyms.

  1. Initialize a knowledge template:
ciak knowledge init

This creates .ciak/knowledge.json.

  1. Edit .ciak/knowledge.json to add your domain terms.

  2. Sync the knowledge into the database:

ciak sync knowledge

You can also:

  • Use --file to point to a custom JSON file.
  • Use --force to clear existing user terms before importing.
  • Use --dry-run to see what would change without applying it.

5. (Optional) Cloud sync your project​

If you are using the SaaS / cloud backend and have a valid license, you can push your scanned project to the cloud API.

From the project root:

# Ensure project is scanned first
ciak scan --embeddings

# Full cloud sync
ciak cloud-sync full --path . --sync-profile full

CIAK will:

  • Load your cloud sync configuration from the license file.
  • Read project data from .ciak/database.db.
  • Upload files, symbols, dependencies, and embeddings (when available in full profile) to the cloud API.

If the local database is missing, you may see:

Local database not found. Run 'ciak scan' first.

6. Configure the MCP server in your IDE​

The CIAK MCP server is a local binary that exposes code intelligence tools to AI assistants in your IDE. Your IDE launches it as a subprocess and communicates with it over stdio.

Configure your IDE to use the ciak-mcp-server binary. The server takes no command-line arguments and auto-detects your project from ~/.ciak/ or the current working directory:

{
  "mcpServers": {
    "ciak": {
      "command": "ciak-mcp-server"
    }
  }
}

For detailed IDE-specific instructions (Windsurf, Cursor, Claude Desktop, VS Code), see the MCP Setup guide.

7. Use CIAK via MCP from an AI client​

Once the MCP server is configured in your IDE, your AI assistant can use tools like:

  • Code search (text or semantic).
  • Analyze symbols.
  • Get related context / related files.
  • Analyze relationships and dependencies.

See the MCP Tools Reference for the full list of available tools and their parameters.

8. Full workflow recap​

Putting it all together for a new repo:

# 1. Install CIAK CLI and MCP server from the official releases
#    (download archive for your OS, extract, move ciak and ciak-mcp-server into PATH)

# 2. (Optional) Activate license
ciak license activate XXXX-XXXX-XXXX-XXXX

# 3. Initialize and scan your project
cd /path/to/your/code
ciak init
ciak scan --embeddings

# 4. Sync knowledge (optional but recommended)
ciak knowledge init
# edit .ciak/knowledge.json
ciak sync knowledge

# 5. (Optional) Cloud sync your project
ciak cloud-sync full --path . --sync-profile full

# 6. Configure MCP server in your IDE (see MCP Setup guide)

You now have:

  • A local CIAK database for your project.
  • Optional domain knowledge imported.
  • Optional project data synced to the cloud.
  • An MCP server configured in your IDE for AI-powered code intelligence.