Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

CLI Reference

Complete reference for all agentful CLI commands, options, and outputs.

Installation

# Local installation
npx @itz4blitz/agentful init
 
# Global installation
npm install -g @itz4blitz/agentful

Commands

agentful init

Initialize agentful in the current directory.

Usage

agentful init
agentful init --bare

Options

OptionTypeDescription
--bareflagSkip creating template files (CLAUDE.md, PRODUCT.md), only create .claude/ and .agentful/ directories

What It Creates

  1. .claude/ directory (if not exists)

    • All agent configurations
    • Command definitions
    • Settings and permissions
    • Skills and capabilities

  2. .agentful/ directory (gitignored)

    • state.json - Current work state
    • completion.json - Feature progress tracking
    • decisions.json - Pending/resolved decisions
    • architecture.json - Detected tech stack

  3. Template files (skipped with --bare)

    • PRODUCT.md - Product specification template
    • CLAUDE.md - Quick start guide

  4. .gitignore update

    • Adds .agentful/ to gitignore

Behavior

If .claude/ already exists, prompts for confirmation:

⚠️  .claude/ directory already exists!
Overwrite? (y/N)
  • y - Removes existing directory and recreates
  • N or any other input - Aborts initialization

Output Example

    ___    __  ____________  ____  ___   ____________
   /   |  / / / /_  __/ __ \/ __ \/ _ | / ____/  _/ /
  / /| | / / / / / / /_/ / /_/ /  __ |/ /    / // /
 / ___ |/ /_/ / / / / _, _/ _, _/ /_/ / /___/ // /
/_/  |_|_____/ /_/_/ /_/ |_/_/ |_|\____/\____/___/
 
                   v1.0.0
 
Creating .claude/ directory structure...
Initializing state files...
  ✓ Created CLAUDE.md
  ✓ Created PRODUCT.md
Added .agentful/ to .gitignore
 
✅ agentful initialized successfully!
 
Next steps:
  1. Edit PRODUCT.md with your product specification
  2. Run: claude
  3. Type: /agentful-start
 
For autonomous 24/7 development:
  /ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"

Exit Codes

  • 0 - Successfully initialized
  • 1 - Initialization failed (directory permissions, user aborted)

agentful status

Display current development progress and state.

Usage

agentful status

Prerequisites

  • Must be run in a directory with .agentful/ folder
  • state.json must exist

Output Sections

1. Current Work

Shows active development task:

Current Status:
 
🔧 Working on: Authentication - JWT implementation
   Phase: backend-implementation
   Iterations: 3

Or if idle:

💤 Idle - no active task
2. Progress Bar

Visual completion percentage:

Progress:
   ████████████░░░░░░░░ 48%
3. Quality Gates

Status of all quality gates:

Quality Gates:
   ✅ Tests Passing
   ❌ No Type Errors
   ✅ No Dead Code
   ❌ Coverage 80
   ⚠️  Security Clean
4. Pending Decisions

If decisions are blocking development:

⚠️  2 pending decisions:
   1. Should auth use JWT or session cookies?
   2. Which database provider?
 
   Run: /agentful-decide
5. Next Actions

Always shows available commands:

Next Actions:
   • /agentful-start    - Continue development
   • /agentful-decide  - Answer pending decisions
   • /agentful-validate- Run quality checks

Error Cases

❌ agentful not initialized in this directory!
Run: npx @itz4blitz/agentful init
❌ State file missing!
Run: npx @itz4blitz/agentful init

Complete Output Example

    ___    __  ____________  ____  ___   ____________
   /   |  / / / /_  __/ __ \/ __ \/ _ | / ____/  _/ /
  / /| | / / / / / / /_/ / /_/ /  __ |/ /    / // /
 / ___ |/ /_/ / / / / _, _/ _, _/ /_/ / /___/ // /
/_/  |_|_____/ /_/_/ /_/ |_/_/ |_|\\____/\\____/___/
 
                   v1.0.0
 
Current Status:
 
🔧 Working on: User authentication system
   Phase: backend-implementation
   Iterations: 7
 
Progress:
   ████████░░░░░░░░░░░░ 35%
 
Quality Gates:
   ❌ Tests Passing
   ❌ No Type Errors
   ✅ No Dead Code
   ❌ Coverage 80
   ✅ Security Clean
 
Next Actions:
   • /agentful-start    - Continue development
   • /agentful-decide  - Answer pending decisions
   • /agentful-validate- Run quality checks

agentful --help

Display help information.

Usage

agentful --help
agentful -h
agentful help

Output

    ___    __  ____________  ____  ___   ____________
   /   |  / / / /_  __/ __ \/ __ \/ _ | / ____/  _/ /
  / /| | / / / / / / /_/ / /_/ /  __ |/ /    / // /
 / ___ |/ /_/ / / / / _, _/ _, _/ /_/ / /___/ // /
/_/  |_|_____/ /_/_/ /_/ |_/_/ |_|\\____/\\____/___/
 
                   v1.0.0
 
USAGE:
  agentful <command>
 
COMMANDS:
  init         Initialize agentful in current directory
  init --bare  Skip creating templates (just .claude/)
  status      Show current development progress
  --help       Show this help message
  --version    Show version
 
AFTER INIT:
  1. Edit PRODUCT.md with your product spec
  2. Run claude to start Claude Code
  3. Type /agentful-start to begin autonomous development
 
FOR 24/7 DEVELOPMENT:
  /ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"

agentful --version

Display agentful version.

Usage

agentful --version
agentful -v

Output

agentful v1.0.0

Exit Codes Summary

CodeMeaning
0Success
1Error (unknown command, initialization failed, missing state)

Environment

Required Files

FilePurposeCreated By
.claude/agentful configurationagentful init
.agentful/state.jsonCurrent stateagentful init
.agentful/completion.jsonProgress trackingagentful init
.agentful/decisions.jsonDecision trackingagentful init
.agentful/architecture.jsonTech stack detectionAgent (automatically)

Optional Files

FilePurposeCreated By
PRODUCT.mdProduct specificationagentful init (skip with --bare)
CLAUDE.mdQuick start guideagentful init (skip with --bare)

Directory Permissions

agentful requires:

  • Read access to current directory
  • Write access to create .claude/ and .agentful/
  • Write access to update .gitignore

Color Scheme

The CLI uses ANSI colors for better readability:

ColorUsage
CyanBanner, branding
GreenSuccess messages, completed items
YellowWarnings, pending items
RedErrors, failures
BlueActive work, information
MagentaNot currently used
Dim/BrightText emphasis

Version Compatibility

agentful Version

Current version: 1.0.0

Check compatibility:

agentful --version

Node.js Requirements

Minimum Node.js version: 18.0.0

Check your version:

node --version

Quick Reference

CommandPurposeCommon Use Case
agentful initStart new projectCreating new agentful project
agentful init --bareConfig onlyAdding to existing project
agentful statusCheck progressSee what's done/in progress
agentful --helpGet helpRemember command syntax
agentful --versionCheck versionDebug version issues

Troubleshooting

"Command not found"

# Use npx instead
npx @itz4blitz/agentful init
 
# Or install globally
npm install -g @itz4blitz/agentful

"Permission denied"

# Check directory permissions
ls -la .
 
# Ensure write access
chmod u+w .

"Already initialized"

# Remove existing .claude/ first
rm -rf .claude .agentful
 
# Then reinitialize
agentful init

State file corruption

# Remove corrupted state
rm .agentful/state.json
 
# Reinitialize (preserves other state)
agentful init --bare

Integration Examples

With npm scripts

{
  "scripts": {
    "agentful:init": "agentful init",
    "agentful:status": "agentful status",
    "start": "claude"
  }
}

With CI/CD

# Check agentful status in CI
- run: agentful status
 
# Validate completion percentage
- run: |
    PERCENT=$(jq -r '.overall' .agentful/completion.json)
    if [ "$PERCENT" -lt 100 ]; then
      echo "Project not complete: $PERCENT%"
      exit 1
    fi

With Git hooks

# .git/hooks/pre-commit
#!/bin/bash
agentful status
echo "Check progress before committing"

See Also