# Task Commands

Complete reference for Taskfile automation commands.

## Installation & Setup

### Install All Dependencies
```bash
task install
```

Runs `uv sync` and `bun install` to install all dependencies.

### Initialize Databases
```bash
task db:init
```

Creates data directories for Neo4j, PostgreSQL, and Redis.

## Development

### Start Development Environment
```bash
task dev
```

Starts all services:

- Docker containers (Neo4j, Postgres, Redis)
- Django API on port 12319
- Tauri development window

`task dev` runs a `dev:kill` preflight first, so a leftover server from a previous run
won't collide with the new one.

### Reap Straggler Dev Processes
```bash
task dev:kill   # alias: task dev:reap
```

`uvicorn --reload` (and the `uv run` wrapper) can swallow `SIGTERM`, so a crashed or
orphaned dev supervisor sometimes leaves the API bound to port 12319 — plus the portless
memory worker — still running. This reaps the uvicorn reload tree and the consolidation
worker by command signature, then frees ports 12319/1420/1421 as a backstop. It runs
automatically before `task dev`; run it by hand if you ever hit "address already in use".

### Start Services Only
```bash
task runners
```

Starts Docker containers without API or client.

### Stop All Services
```bash
task teardown
```

Stops and removes Docker containers.

### Environment Check
```bash
task check
```

Verifies the development environment is ready (prerequisites, directories, dependencies).

## API Commands

### Run Django Server
```bash
task api:runserver
```

Starts Django development server on `http://127.0.0.1:12319`.

### Django Shell
```bash
task api:shell
```

Opens Django interactive shell.

### Database Migrations

Create migration files:
```bash
task api:makemigrations
```

Apply migrations:
```bash
task api:migrate
```

## Client Commands

### Start Tauri Dev Mode
```bash
task client:dev
```

Launches Tauri window with hot reload.

### Build Client
```bash
task client:build
```

Builds production client bundle.

### Preview Production Build
```bash
task client:preview
```

Serves the production web build locally (no Tauri packaging).

### Mobile (Android)
```bash
task client:android:init    # Bootstrap the Tauri Android project (first time)
task client:dev:android     # Run on a connected device with hot reload
task client:build:android   # Build a debug-signed APK
```

## Database Management

### PostgreSQL

Open PostgreSQL shell:
```bash
task db:shell:postgres
```

Create backup:
```bash
task db:backup
```

Backups saved to `./backups/postgres_YYYYMMDD_HHMMSS.sql`

Restore from backup:
```bash
task db:restore BACKUP_FILE=backups/postgres_20231127_120000.sql
```

### Redis

Open Redis CLI:
```bash
task db:shell:redis
```

### Neo4j

Neo4j Browser: [http://localhost:7474](http://localhost:7474)

### Clean All Data

!!! danger "Destructive Operation"
    This permanently deletes all database data!

```bash
task db:clean
```

You will be prompted for confirmation.

### Export / Import Memory

Round-trippable, ID-stable snapshots of the agent memory graph (conversations,
facts, entities, strategies, goals + the PostgreSQL audit mirror). Exports are
text-only — embeddings are regenerated on import, so files stay small and
git-diffable.

```bash
# Export every channel to data/memory_exports/<ts>_all.json
task memory:export

# Export one channel
task memory:export -- --channel _global

# Import (idempotent MERGE-on-id; embeddings recomputed from text)
task memory:import -- --input data/memory_exports/<file>.json

# Replace a channel exactly (wipe that channel for the user, then import)
task memory:import -- --input <file>.json --mode replace --channel _global
```

`--mode merge` (default) upserts and leaves other data untouched; `--mode replace`
wipes the target channel first. Pass `--dry-run` to parse + summarize without writing.

## Testing

### Run All Tests
```bash
task test
```

Runs Django test suite.

### Quick Tests (no model loading)
```bash
task test:quick
```

Runs the subset of tests that don't load translation/embedding models.

### Run Specific Test
```bash
uv run python api/manage.py test agentx_ai.tests.TranslationKitTest
```

### Run Single Test Method
```bash
uv run python api/manage.py test agentx_ai.tests.TranslationKitTest.test_translate_to_french
```

### Client Tests (Vitest)
```bash
task test:client
```

## Documentation

The docs site is an Astro project under `docs-site/`.

### Install Docs Dependencies
```bash
task docs:install
```

### Serve Documentation Locally
```bash
task docs:serve   # alias: task docs:dev
```

Serves the Astro docs site with HMR at [http://localhost:4321](http://localhost:4321).

### Build Documentation
```bash
task docs:build
```

Builds the static site to `docs-site/dist/`. Use `task docs:preview` to preview the build.

### Deploy Documentation
```bash
task docs:deploy
```

Deploys the docs site to Vercel (requires the Vercel CLI + login).

### Lint the OpenAPI spec
```bash
task api:spec:lint
```

Validates the root `OpenApi.yaml` (the machine-readable mirror of the
[API reference](../api/endpoints.md)) with Redocly.

## Utility Commands

### Default Task
```bash
task
```

Runs sanity check and prompts to start development environment.

### List All Tasks
```bash
task --list-all
```

Shows every available task with descriptions (`task --list` shows only the documented top-level ones).

### Task Help
```bash
task --help
```

Displays Taskfile help information.

## Task Dependencies

Some tasks automatically run prerequisites:

- `task dev` → starts Docker services, then runs the API and client concurrently
- `task setup` → runs `task install`, `task db:init`, and `task check`
- `task db:full-init` → creates directories, starts containers, then initializes schemas

## Environment-Specific Tasks

### Development
```bash
# Quick iteration cycle
task dev              # Start everything
# Make changes...
task test             # Verify changes
task teardown         # Stop when done
```

### Testing
```bash
# Run specific tests during development
uv run python api/manage.py test agentx_ai --keepdb
```

### Production Build
```bash
task client:build     # Build optimized client
task api:migrate      # Ensure migrations are applied
```

## Custom Task Variables

Some tasks accept variables:

### Postgres Restore
```bash
task db:restore BACKUP_FILE=path/to/backup.sql
```

## Debugging Tasks

### Verbose Output
```bash
task --verbose dev
```

### Dry Run
```bash
task --dry dev
```

Shows what would be executed without running commands.

## Tips & Tricks

### Run Multiple Commands
```bash
task install && task db:init && task dev
```

### Background Execution
```bash
task runners &  # Start services in background
```

### Watch Mode
```bash
# API auto-reloads on file changes
task api:runserver

# Client has HMR enabled
task client:dev
```

### Quick Database Reset
```bash
task teardown && task db:clean && task db:init && task runners
```

!!! warning
    This deletes all data!

## More Task Groups

Run `task --list-all` for the full set (120+ tasks). Other groups worth knowing:

| Group | Examples | Purpose |
|-------|----------|---------|
| `mcp:*` | `mcp:servers`, `mcp:tools`, `mcp:resources`, `mcp:health` | Inspect MCP servers/tools (API must be running) |
| `auth:*` | `auth:setup`, `auth:setup:force`, `auth:check` | Manage the root password (Phase 17 auth) |
| `cluster:*` | `cluster:new`, `cluster:up`, `cluster:migrate`, `cluster:down`, `cluster:status`, `cluster:list` | Production deployment unit — single or multi-instance (`CLUSTER=name`) |
| `models:*` | `models:download`, `models:cache`, `models:clear`, `warmup:embeddings` | HuggingFace model management |
| `check:*` | `check:static`, `check:types`, `check:build` | Static analysis (lint + types + build) |
| `lint:*` / `format:*` | `lint:python`, `lint:client`, `format:python`, `format:client` | Lint and format |
| `logs:*` / `debug:*` | `logs:api`, `logs:docker`, `logs:keys:status`, `logs:seal`, `logs:rotate-keys`, `logs:rotate-keys:deep`, `debug:env`, `debug:ports` | Logging, diagnostics, and encrypted-archive key management |
| `release:*` | `release:build`, `release:check`, `versions:sync` | Build and release |

## Next Steps

- [Development Setup](setup.md) - Configure your environment
- [Testing Guide](testing.md) - Write and run tests
- [Contributing](contributing.md) - Contribution workflow