@agentuity/cli

The Agentuity command line tool. Project scaffolding, dev server, build, deploy, cloud resource management.

Requirements

• Bun 1.3+ or Node.js 24+

Installation

# Global installation
bun install -g @agentuity/cli
# or
npm install -g @agentuity/cli

# Local installation
bun add -d @agentuity/cli

Usage

# Show banner and help
agentuity

# Top-level commands
agentuity auth login
agentuity project create my-app
agentuity build
agentuity dev

# Cloud commands
agentuity cloud keyvalue set mykey myvalue
agentuity cloud agents
agentuity cloud env list
agentuity cloud env set MY_SECRET value --secret

# AI commands
agentuity ai capabilities show
agentuity ai prompt llm
agentuity ai schema show

# Coder Hub commands
agentuity coder config set url https://hub.example.com
agentuity coder config set apikey agc_...
agentuity coder start
agentuity coder ls
agentuity coder inspect codesess_abc123

# Global options
agentuity --log-level=debug cloud keyvalue list
agentuity --config=/custom/path/production.yaml project list

Coder Hub commands use the active CLI profile for default Hub configuration. You can override the stored Hub URL per command with --hub-url, or use AGENTUITY_CODER_HUB_URL / AGENTUITY_CODER_API_KEY as environment overrides.

Configuration

The CLI loads configuration from ~/.config/agentuity/production.yaml by default.

Example config:

# ~/.config/agentuity/production.yaml
api:
   endpoint: https://api.agentuity.com
   token: your-token-here

defaults:
   environment: development
   region: us-west-2

You can override the config path with --config:

agentuity --config=/path/to/production.yaml [command]

Log Levels

Control output verbosity with --log-level:

# Available levels: debug, trace, info, warn, error
agentuity --log-level=debug example create test
agentuity --log-level=error example list

Command Structure

Commands are organized into groups:

• Top-level: auth, project, version, build (alias: bundle), dev
• Cloud (cloud): keyvalue, agents, env, and deployment-related commands
• AI (ai): capabilities, prompt, schema
• Hidden: profile (internal use only)

Commands are auto-discovered from the src/cmd/ directory. Each command is a directory with an index.ts file.

Simple Command

// src/cmd/version/index.ts
import type { CommandDefinition, CommandContext } from '@agentuity/cli';
import { Command } from 'commander';

export const versionCommand: CommandDefinition = {
    name: 'version',
    description: 'Display version information',

    register(program: Command, ctx: CommandContext) {
        program
            .command('version')
            .description('Display version information')
            .action(() => {
                console.log('v1.0.0');
            });
    },
};

export default versionCommand;

Command with Options

// src/cmd/deploy/index.ts
import type { CommandDefinition, CommandContext } from '@agentuity/cli';
import { Command } from 'commander';

interface DeployOptions {
    force: boolean;
    dryRun: boolean;
}

export const deployCommand: CommandDefinition = {
    name: 'deploy',
    description: 'Deploy application',

    register(program: Command, ctx: CommandContext) {
        program
            .command('deploy <environment>')
            .description('Deploy to an environment')
            .option('-f, --force', 'Force deployment', false)
            .option('--dry-run', 'Dry run mode', false)
            .action(async (environment: string, options: DeployOptions) => {
                const { logger, config } = ctx;

                logger.info(`Deploying to: ${environment}`);

                if (options.dryRun) {
                    logger.info('Dry run - no changes made');
                    return;
                }

                // Deployment logic here
            });
    },
};

export default deployCommand;

Command with Subcommands

// src/cmd/project/index.ts
import type { CommandDefinition, CommandContext } from '@agentuity/cli';
import { Command } from 'commander';
import { createSubcommand } from './create';
import { listSubcommand } from './list';

export const projectCommand: CommandDefinition = {
    name: 'project',
    description: 'Manage projects',
    subcommands: [createSubcommand, listSubcommand],

    register(program: Command, ctx: CommandContext) {
        const cmd = program.command('project').description('Manage projects');

        if (this.subcommands) {
            for (const sub of this.subcommands) {
                sub.register(cmd, ctx);
            }
        }

        cmd.action(() => cmd.help());
    },
};

export default projectCommand;

// src/cmd/project/create.ts
import type { SubcommandDefinition, CommandContext } from '@agentuity/cli';
import { Command } from 'commander';

interface CreateOptions {
    template: string;
}

export const createSubcommand: SubcommandDefinition = {
    name: 'create',
    description: 'Create a new project',

    register(parent: Command, ctx: CommandContext) {
        parent
            .command('create <name>')
            .description('Create a new project')
            .option('-t, --template <template>', 'Project template', 'default')
            .action(async (name: string, options: CreateOptions) => {
                const { logger } = ctx;
                logger.info(`Creating project: ${name}`);
                // Implementation here
            });
    },
};

Command Context

Every command receives a CommandContext with:

• config: Loaded YAML configuration
• logger: Structured logger (respects --log-level)
• options: Global CLI options

.action(async (args, options) => {
    const { logger, config } = ctx;

    // Use logger for output
    logger.info('Starting...');
    logger.debug('Debug info');
    logger.warn('Warning');
    logger.error('Error occurred');

    // Access config
    const apiToken = config.api?.token;
});

API

Types

• CommandDefinition - Main command definition
• SubcommandDefinition - Subcommand definition
• CommandContext - Context passed to commands
• Config - Configuration object (Record<string, unknown>)
• LogLevel - Log level type ('debug' | 'trace' | 'info' | 'warn' | 'error')
• GlobalOptions - Global CLI options

Functions

• createCLI(version: string) - Create CLI program
• registerCommands(program, commands, ctx) - Register commands
• discoverCommands() - Auto-discover commands from src/cmd/
• loadConfig(path?) - Load YAML config
• showBanner(version) - Show startup banner

License

Apache 2.0