CLI Reference

Commands

Command	Description
`npx @idosal/agentcraft`	Guided setup: detect CLIs, install hooks, start server, open browser
`agentcraft start`	Start server. Installs hooks if missing. Options: `-p`/`--port`, `--no-browser`, `-d`/`--daemon`, `--all-projects`
`agentcraft stop`	Stop a running server (SIGTERM, then SIGKILL after 5s)
`agentcraft status`	Show server PID, port, and uptime
`agentcraft logs`	Read retained server output. Options: `--port`, `--lines`, `--follow`
`agentcraft open`	Open the UI in a browser (server must be running)
`agentcraft install`	Install hooks only (no server). `--force` to reinstall
`agentcraft uninstall`	Preview or remove AgentCraft-managed project files; optionally purge user data
`agentcraft restore`	Replay an automatic uninstall backup manifest
`agentcraft logout`	Clear auth tokens from `~/.agentcraft/auth.json`
`agentcraft doctor`	Run diagnostics

Default Flow

Running npx @idosal/agentcraft with no arguments performs the guided setup:

Shows the first-install notice and asks before changing managed files
Detects supported provider CLIs and config directories
Installs or updates repo-local provider integration files such as .claude/settings.local.json, .cursor/hooks.json, .codex/hooks.json, and .opencode/plugins/agentcraft.js
Preserves existing user configuration and removes legacy global AgentCraft entries that would fire duplicate events
Starts the server on port 2468
Opens the browser UI

Server Modes

Foreground (default)

npx @idosal/agentcraft

The server runs in the foreground. Press Ctrl+C to stop.

Daemon

npx @idosal/agentcraft start --daemon   # or: start -d
npx @idosal/agentcraft stop             # Stop the daemon later

Custom Port

npx @idosal/agentcraft start --port 3002   # or: start -p 3002

All Projects

By default, only agents from the current working directory are shown. To display sessions from all projects:

npx @idosal/agentcraft start --all-projects

Diagnostics

npx @idosal/agentcraft doctor

Checks:

Supported provider CLIs, authentication, and repo-local hooks/plugins
Node.js compatibility and native terminal build prerequisites
Server, health endpoint, port, LAN, and trusted-origin status
AgentCraft configuration and install integrity
Container runtime and Codex sandbox prerequisites
Optional Bedrock and Vertex AI configuration

Hook Management

Install / Reinstall

npx @idosal/agentcraft install --force

Hooks are identified by the PLUGIN_DIR path in their command strings. AgentCraft hooks are merged with your existing hooks — user-defined hooks are never touched.

Uninstall

npx @idosal/agentcraft uninstall --dry-run
npx @idosal/agentcraft uninstall

Uninstall removes AgentCraft-managed provider entries and project assets while preserving user-defined hooks and unrelated config. The managed set includes the AgentCraft collaboration block, managed .gitignore entries, .campaign/, .agentcraft/, and the installed OpenClaw skill.

Options:

Option	Purpose
`--dry-run`	Preview the managed removal set without changing files
`--purge`	Also remove `~/.agentcraft`, signed-in state, and AgentCraft-installed cloudflared files
`--yes`	Skip the confirmation prompt
`--backup-to <path>`	Store the automatic backup session at a custom location

Every real uninstall creates a timestamped backup manifest before changing files. Standard backups live under ~/.agentcraft/uninstall/; purge backups are stored outside that directory so they survive the purge.

Restore

npx @idosal/agentcraft restore                # newest backup
npx @idosal/agentcraft restore --list         # available sessions
npx @idosal/agentcraft restore --from <path>  # selected session

Restore replays the selected uninstall manifest, including modified files and removed directories. Use --force only when AgentCraft should overwrite a directory that was recreated after uninstall. Applied manifests are marked to prevent accidental double restoration.

Server Logs

Foreground and daemon server output is retained per port:

npx @idosal/agentcraft logs
npx @idosal/agentcraft logs --lines 500
npx @idosal/agentcraft logs --port 3002 --follow

Logs live at ~/.agentcraft/logs/server-<port>.log and are the fastest way to inspect startup, provider-detection, and runtime failures.

Configuration Files

All AgentCraft config lives in ~/.agentcraft/:

File	Purpose
`config.json`	Port, autoOpenBrowser, API keys
`auth.json`	Auth tokens (0o600 permissions)
`server.pid`	PID of daemon-mode server
`mission-history.json`	Persisted completed missions
`settings.json`	UI preferences and orchestration settings
`logs/server-<port>.log`	Retained foreground and daemon output
`task-queue.json`	Persisted Campaign plans and tasks
`task-memory/`	Per-task traces and evidence
`plan-memory/`	Campaign workpads, reports, and evidence

On this page