cadmus-cli 0.1.2

The `cadmus` command: creates Cadmus projects and models
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

---
title: Getting started
section: Getting started
order: 20
summary: Install the cadmus command and build a first project, step by step.
---

This page takes you from nothing to a running site with an admin and an API, in about ten
minutes (most of it the first compile).

## What you need

[Rust](https://www.rust-lang.org/tools/install), a recent stable version installed with
`rustup`. Nothing else: the first project uses SQLite, a database kept in a single file.

## 1. Install the cadmus command

```sh
cargo install cadmus-cli
```

This installs `cadmus`, which creates projects and models. Check it with `cadmus --version`.

## 2. Create a project

```sh
cadmus new blog
cd blog
```

This writes a ready-to-run project (see [Project layout](project-layout.md)), including a
`.env` file with a fresh secret key. For PostgreSQL or MySQL instead of SQLite, use
`cadmus new blog --database postgres` (or `mysql`) and edit the address in `.env`.

## 3. Describe your data

A blog post with a title, a body, a published flag and a view count:

```sh
cadmus generate model Post title:string body:text published:bool views:int
```

This writes `src/models/post.rs` and registers it in `src/models/mod.rs`. The field types
are `string`, `text`, `int`, `bigint`, `float`, `bool`, `datetime`, `date`, `json`, `file`
(an uploaded file) and `references` (a link to another model). Add `?` to make a field
optional, as in `rating:float?`. See [Models](models.md) for the details.

## 4. Create the table

```sh
cargo run -- makemigrations   # writes src/migrations/m0001_initial.rs
cargo run -- migrate          # creates the table in the database
```

The first run compiles the project, which takes a minute or two; later runs are quick.
[Migrations](migrations.md) explains what these do.

## 5. Make an account for yourself

```sh
cargo run -- createsuperuser --username admin
```

It asks for a password. A *superuser* can do everything, including managing other
accounts.

## 6. Start the server

```sh
cargo run -- serve
```

Then open:

| Address | What you see |
|---|---|
| <http://localhost:3000/admin> | the admin site: log in, then add and edit posts |
| <http://localhost:3000/api/docs> | the API documentation, where you can try every request |
| <http://localhost:3000/> | a public status page: is the service up, does the database answer |

## 7. Change something

Give posts an optional summary: in `src/models/post.rs`, add this line to the `Model`
struct:

```rust
pub summary: Option<String>,
```

Then:

```sh
cargo run -- makemigrations   # notices the new field, writes m0002_post_summary.rs
cargo run -- migrate          # adds the column; existing posts keep their data
```

That is the whole loop: change the models, make a migration, apply it.

## Where to go next

- [Models](models.md): field types and the admin options for each model.
- [The admin site](admin.md): lists, filters, actions and forms.
- [The REST API](rest-api.md): what other programs can do, and how they log in.
- [Building with AI agents](ai-agents.md): let a coding agent build on Cadmus for you.