---
title: "Use code blocks"
url: "https://docs.alisx.com/how-to/alis-build/use-code-blocks/"
---
# Use code blocks

Install a code block into a service to start from a working, versioned snapshot of another service, keep it upgraded, and publish your own service as a block for other products.

A code block is a service's build folder (with `infra/` split out) plus its protos, templated so that any product can install it. Install and upgrade run on the platform: the generated files are committed to a `block/*` branch in both the product's build repo and the build environment's definitions repo, and the CLI merges that branch into the main branch of both repos and pushes.

## Prerequisites

- A service to install into, with both repositories cloned.
- The block id. Browse blocks in the console at `/build/blocks` (tabs **Stable**, **Release Candidate**, **Beta**, **Alpha**, **Experimental**) or list them with the CLI.

## Browse

```bash title="Terminal"
alis blocks list acme.sh.orders.v1
alis blocks versions <block-id>
```

`list` shows the service's installed blocks and the blocks available to it; `versions` lists a block's versions, newest first. A block's console page has **About**, **Documentation**, **Versions**, **Instances** and **Help**.

## Install

```bash title="Terminal"
alis blocks install <block-id> acme.sh.orders.v1
```

- `--version 1.2.0` installs a specific version (default: the latest stable).
- `--build-folder <folder>` places the block's build files under a subfolder of the service (default `./`).
- `--no-merge` skips the local merge; run `alis blocks merge <block-id>` later.
- `--async` returns the operation; resume with `alis operations wait`, then run `alis blocks merge` (a wait never merges).

Blocks with a dedicated service, such as `resources`, generate their files from a typed config: pass `--config <file>` (JSON or YAML, `-` for stdin). Missing config fails fast with `CONFIG_REQUIRED`. The block's skill documents the schema: `alis skills load block-<block-id>`.

When the result's `next` names the block's skill, load it before configuring or deploying. Then continue the normal loop: `alis define` (the block added protos), build and deploy.

## Upgrade and uninstall

```bash title="Terminal"
alis blocks upgrade <block-id> acme.sh.orders.v1
alis blocks uninstall <block-id> acme.sh.orders.v1
```

`upgrade` moves the instance to `--version` (default: the latest, GA preferred) through the same block branch and merge; `--config` replaces a dedicated-service block's stored config. `uninstall` deletes the instance's unmerged block branches; files already merged into the main branch stay. Use `--instance blocks/<id>/instances/<n>` when a block is installed more than once.

## Send feedback

```bash title="Terminal"
alis blocks feedback <block-id> "The install left the bucket name unset"
```

Feedback reaches the block's owners as a conversation; repeat feedback on the same block lands on your open thread.

## Publish your service as a block

```bash title="Terminal"
alis blocks accounts
alis blocks create <block-id> acme.sh.orders.v1 --display-name "Orders" --account accounts/<id> --tagline "Order capture and fulfilment"
```

`create` uploads the current files as the block's first version, registers the service as the block's source and scaffolds `.skill/SKILL.md` in the service folder; commit that file. The block id is immutable. Local environment files (`.alis`, `.env*`, `key.json`) are never uploaded.

Keep building the source service, push, then cut versions:

```bash title="Terminal"
alis blocks publish <block-id> acme.sh.orders.v1 --release-level BETA --notes "Adds refunds"
```

`--release-level` is `GA`, `RC`, `BETA`, `ALPHA` or `EXPERIMENTAL`. The source service publishes from its trunk's latest commits; a service that installed the block must choose `--from trunk`, `--from contribution` or `--branch <name>`, or pin both commits with `--define-commit` and `--build-commit`. The `.skill/` folder of the most stable version becomes the registry skill `block-<block-id>`. The TUI's ++shift+b++ and ++shift+p++ actions offer the same with a per-file review step.

## Related

- [How code blocks work](https://docs.alisx.com/explanation/code-blocks.md)
- [Define your API](https://docs.alisx.com/how-to/alis-build/define-your-api.md)
- [Agents, skills and the CLI](https://docs.alisx.com/explanation/agents-skills-cli.md)