# Nextcloud Impl Occ Commands

> >

- **Type:** Skill
- **Install:** `agentstack add skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-impl-occ-commands`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** https://github.com/Impertio-Studio/Nextcloud-Claude-Skill-Package/tree/main/skills/source/nextcloud-impl/nextcloud-impl-occ-commands

## Install

```sh
agentstack add skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-impl-occ-commands
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# nextcloud-impl-occ-commands

## Quick Reference

### Invocation

```bash
sudo -u www-data php occ [command] [arguments] [options]
```

**NEVER** run occ as root -- file permissions will break and Nextcloud will become inaccessible. ALWAYS use the web server user (`www-data` on Debian/Ubuntu, `apache` on RHEL/CentOS, `nginx` on Alpine).

### Built-in Command Categories

| Category | Prefix | Purpose |
|----------|--------|---------|
| Maintenance | `maintenance:` | Maintenance mode, repair, updates |
| User Management | `user:` | Add, delete, list, enable/disable users |
| App Management | `app:` | Enable, disable, list, update apps |
| Configuration | `config:` | System and app config get/set |
| Files | `files:` | Scan, cleanup, transfer ownership |
| Background Jobs | `background:` | Set background job mode |
| Database | `db:` | Migrations, conversions |
| Encryption | `encryption:` | Enable, disable, key management |
| Logging | `log:` | Log level management |
| Status | `status` | Installation status as JSON |

### Essential Built-in Commands

| Command | Description |
|---------|-------------|
| `maintenance:mode --on` | Enable maintenance mode |
| `maintenance:mode --off` | Disable maintenance mode |
| `maintenance:repair` | Run repair steps |
| `upgrade` | Run database upgrade after Nextcloud update |
| `user:add --display-name="Name" --group="group" userid` | Create user |
| `user:delete userid` | Delete user |
| `user:list` | List all users |
| `user:enable userid` | Enable user |
| `user:disable userid` | Disable user |
| `app:enable appid` | Enable an app |
| `app:disable appid` | Disable an app |
| `app:list` | List installed apps and status |
| `app:update --all` | Update all apps |
| `config:system:set key --value=val` | Set system config |
| `config:system:set key --value=val --type=boolean` | Set typed system config |
| `config:system:get key` | Get system config value |
| `config:app:set appid key --value=val` | Set app config |
| `config:app:get appid key` | Get app config value |
| `config:list` | Export all config as JSON |
| `files:scan --all` | Scan all user files |
| `files:scan --path="/user/files/folder"` | Scan specific path |
| `files:cleanup` | Clean up orphaned file cache entries |
| `files:transfer-ownership source dest` | Transfer file ownership |
| `background:cron` | Set background jobs to cron mode |
| `background:ajax` | Set background jobs to AJAX mode |
| `background:webcron` | Set background jobs to webcron mode |
| `status --output=json` | Show installation status as JSON |

### Common Config Commands

```bash
# Set trusted domain
sudo -u www-data php occ config:system:set trusted_domains 1 --value=cloud.example.com

# Enable debug mode
sudo -u www-data php occ config:system:set debug --value=true --type=boolean

# Set Redis memcache
sudo -u www-data php occ config:system:set memcache.distributed --value='\OC\Memcache\Redis'

# Set overwrite CLI URL (required for cron)
sudo -u www-data php occ config:system:set overwrite.cli.url --value='https://cloud.example.com'

# Set default phone region (NC 28+)
sudo -u www-data php occ config:system:set default_phone_region --value='NL'
```

### Critical Warnings

**NEVER** run occ as root -- this changes file ownership and breaks Nextcloud. ALWAYS use `sudo -u www-data php occ`.

**NEVER** use `files:scan --all` on large installations without scheduling during off-peak hours -- it locks the file cache and degrades performance. ALWAYS target specific paths with `--path` when possible.

**NEVER** forget to run `maintenance:mode --on` before major operations (upgrades, migrations) -- users may corrupt data during the operation.

**NEVER** run `upgrade` without a database backup -- failed upgrades can leave the database in an inconsistent state.

**ALWAYS** use `--type=boolean` when setting boolean config values -- without it, `true` is stored as a string, not a boolean.

**ALWAYS** use `--type=integer` when setting numeric config values -- without it, numbers are stored as strings.

**ALWAYS** run `maintenance:repair` after manual file system changes -- the file cache must be synchronized.

---

## Decision Tree: Which Command to Use

```
Need to administer Nextcloud from CLI?
├── Managing users? → user:add / user:delete / user:list / user:enable / user:disable
├── Managing apps? → app:enable / app:disable / app:list / app:update
├── Changing config? → config:system:set / config:app:set
├── File operations? → files:scan / files:cleanup / files:transfer-ownership
├── Upgrading? → maintenance:mode --on → upgrade → maintenance:mode --off
├── Background jobs? → background:cron (recommended for production)
└── Creating custom command? → Extend Symfony Command (see Pattern 1 below)
```

---

## Essential Patterns

### Pattern 1: Custom Command with Arguments and Options

```php
setName('myapp:process-items')
            ->setDescription('Process pending items for a user')
            ->addArgument(
                'user',
                InputArgument::REQUIRED,
                'The user ID to process items for'
            )
            ->addOption(
                'force',
                'f',
                InputOption::VALUE_NONE,
                'Force reprocessing of already processed items'
            )
            ->addOption(
                'limit',
                'l',
                InputOption::VALUE_REQUIRED,
                'Maximum number of items to process',
                100 // default value
            );
    }

    protected function execute(InputInterface $input, OutputInterface $output): int {
        $userId = $input->getArgument('user');
        $force = $input->getOption('force');
        $limit = (int) $input->getOption('limit');

        $output->writeln("Processing items for user: {$userId}");

        $count = $this->service->processItems($userId, $force, $limit);

        $output->writeln("Processed {$count} items successfully.");
        return Command::SUCCESS;
    }
}
```

### Pattern 2: Register Command in info.xml

```xml

    myapp
    My App
    
    
        OCA\MyApp\Command\ProcessItems
        OCA\MyApp\Command\CleanupData
    

```

**ALWAYS** register commands in `appinfo/info.xml` -- unregistered commands are invisible to occ.

**ALWAYS** use the fully qualified class name (FQCN) including the `OCA\` namespace.

### Pattern 3: Output Formatting with Tables and Progress Bars

```php
use Symfony\Component\Console\Helper\Table;
use Symfony\Component\Console\Helper\ProgressBar;

protected function execute(InputInterface $input, OutputInterface $output): int {
    // Table output
    $table = new Table($output);
    $table->setHeaders(['User', 'Files', 'Quota Used']);
    $table->addRow(['alice', '1,234', '4.2 GB']);
    $table->addRow(['bob', '567', '1.8 GB']);
    $table->render();

    // Progress bar
    $items = $this->service->getPendingItems();
    $progressBar = new ProgressBar($output, count($items));
    $progressBar->start();

    foreach ($items as $item) {
        $this->service->process($item);
        $progressBar->advance();
    }

    $progressBar->finish();
    $output->writeln(''); // newline after progress bar
    return Command::SUCCESS;
}
```

### Pattern 4: Command with Confirmation and Error Handling

```php
use Symfony\Component\Console\Question\ConfirmationQuestion;

protected function execute(InputInterface $input, OutputInterface $output): int {
    $userId = $input->getArgument('user');

    if (!$input->getOption('force')) {
        $helper = $this->getHelper('question');
        $question = new ConfirmationQuestion(
            "Delete all data for user {$userId}? (y/N) ",
            false
        );
        if (!$helper->ask($input, $output, $question)) {
            $output->writeln('Aborted.');
            return Command::SUCCESS;
        }
    }

    try {
        $this->service->deleteUserData($userId);
        $output->writeln("Data deleted for {$userId}.");
        return Command::SUCCESS;
    } catch (\Exception $e) {
        $output->writeln("Failed: {$e->getMessage()}");
        return Command::FAILURE;
    }
}
```

### Pattern 5: Upgrade Workflow

```bash
# 1. Enable maintenance mode
sudo -u www-data php occ maintenance:mode --on

# 2. Create database backup
mysqldump --single-transaction -u nextcloud -p nextcloud_db > backup.sql

# 3. Update Nextcloud files (download or package manager)

# 4. Run database upgrade
sudo -u www-data php occ upgrade

# 5. Run repair steps
sudo -u www-data php occ maintenance:repair

# 6. Disable maintenance mode
sudo -u www-data php occ maintenance:mode --off

# 7. Verify status
sudo -u www-data php occ status --output=json
```

**ALWAYS** follow this exact sequence for upgrades -- skipping steps leads to broken installations.

---

## Symfony Console Argument and Option Types

### InputArgument Modes

| Mode | Behavior |
|------|----------|
| `InputArgument::REQUIRED` | Must be provided |
| `InputArgument::OPTIONAL` | May be omitted (provide default) |
| `InputArgument::IS_ARRAY` | Accepts multiple values |

### InputOption Modes

| Mode | Behavior |
|------|----------|
| `InputOption::VALUE_NONE` | Boolean flag (`--force`) |
| `InputOption::VALUE_REQUIRED` | Must have value (`--limit=10`) |
| `InputOption::VALUE_OPTIONAL` | Value optional (`--format` or `--format=json`) |
| `InputOption::VALUE_IS_ARRAY` | Multiple values (`--exclude=a --exclude=b`) |

### Output Formatting Tags

| Tag | Appearance |
|-----|------------|
| `text` | Green text |
| `text` | Yellow text |
| `text` | Black text on cyan background |
| `text` | White text on red background |

---

## Reference Links

- [references/methods.md](references/methods.md) -- Command class, built-in commands reference
- [references/examples.md](references/examples.md) -- Custom command and built-in command usage examples
- [references/anti-patterns.md](references/anti-patterns.md) -- Common occ mistakes and corrections

### Official Sources

- https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html
- https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/commands.html
- https://symfony.com/doc/current/console.html

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** [Impertio-Studio/Nextcloud-Claude-Skill-Package](https://github.com/Impertio-Studio/Nextcloud-Claude-Skill-Package)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-impl-occ-commands
- Seller: https://agentstack.voostack.com/s/impertio-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.