# Use your Giz account from the command line

The `giz` command also works with your Giz account: AI models, media jobs, Drive, workspace tables,
Computers, Apps, plugins and Agents. These commands need no toolchain. The npm package runs them at once
after `npm install -g @gizai/cli`. giz.ai CLI 2.0 had the same commands, options, output and errors, so a
script written for 2.0 keeps working.

- `--json` writes the result, or the error, as JSON. Use it in scripts and agents.
- `--org ORGANIZATION` (or `GIZ_ORGANIZATION`) picks the organization to work in.
- `--base-url URL` (or `GIZ_URL`) uses another Giz deployment than `https://www.giz.ai`.
- Exit status: `0` success, `1` the request failed or was refused (the error and a hint are on standard
  error), `2` the command line is wrong.
- `giz help COMMAND` prints the usage of each command.

## Sign in

```sh
giz auth login      # confirm the code in the browser; --device only prints the address
giz auth status     # who is signed in
giz auth logout
```

- The sign-in is kept in `~/.config/giz/credentials.json` (`GIZ_CONFIG` names another file). giz.ai CLI 2.0
  reads the same file, so both share one sign-in.
- The same sign-in also signs `giz deploy`, `giz api` and `giz publish` in to GizStack.
- In CI, set `GIZ_TOKEN` instead of signing in.

### API keys and credit

```sh
giz api-key create "My app" --scopes giz.inference,giz.read --expires 2027-01-01T00:00:00Z
giz api-key list
giz api-key revoke key_...
giz credits
```

- `create` shows the key's secret once. Keep it then.
- `credits` prints your purchased and plan credit, when plan credit resets and this month's spend. In a
  workspace it also prints the monthly budget. Read it before paid batch work.

## Models and media

```sh
giz model list --type image --search flux
giz model get MODEL                                # the model and its live input schema
giz chat MODEL "Why is the sky blue? Two sentences."
giz chat MODEL --input '{"messages": [{"role": "user", "content": "Hi"}]}'
giz generate image "a lighthouse at dawn" --model MODEL
giz generate video "the lighthouse, waves rising" --image ./lighthouse.png
giz job wait JOB
```

- `chat` answers at once. `generate` and `model run` start a job and print it.
- The kinds of `generate` are `image`, `video`, `audio`, `music` and `talking-head`.
- `--image LOCAL_PATH` and `--audio LOCAL_PATH` upload a reference. `--upload FIELD=LOCAL_PATH` uploads a file
  into any input field. `--input JSON` gives the whole input.
- `giz job list --limit N`, `giz job get JOB` and `giz job cancel JOB` manage jobs. `giz job wait JOB` exits 1
  unless the job completed, so a script can stop at a failed job.
- `giz upload LOCAL_PATH` uploads a file and prints its URL, for a model input.

## Drive

```sh
giz drive ls /
giz drive search "invoice 2026"
giz drive read /notes/plan.md
giz drive write /notes/plan.md --file ./plan.md     # or --content TEXT
giz drive mkdir /reports
giz drive move /notes/plan.md /reports/plan.md
giz drive delete /reports/old.md
```

## Workspace tables

```sh
giz table list                                      # the workspace's tables
giz table get task                                  # its fields and actions
giz table read TABLE_PATH --input '{"limit": 20}'
giz table write TABLE_PATH --input '{"create": [{"title": "Call the supplier"}]}'
giz table action task close --id 41,42 --input '{}'
```

- `read` takes filters, a sort and totals in `--input` as well as `limit`. `write` creates, updates (`update`, with
  each row's `id`) and removes (`remove`) up to 200 rows, as one change that people can undo.
- `giz table get` lists a table's actions. `giz table action` runs one on the rows of `--id`, with the
  permissions of the person signed in.

## Computers

```sh
giz computer list
giz computer start NAME                             # also get and stop
giz computer exec --computer NAME --cwd /work -- make test
ssh -o ProxyCommand='giz computer ssh %h %p' user@NAME
```

- `exec` runs the words after `--` on the Computer. Its exit status is the command's. `--stdin TEXT` or
  `--stdin-file LOCAL_PATH` gives its input, and `--deadline-ms N` stops it after N milliseconds.
- Without `--computer`, a command uses your default Computer.
- The `ssh` line reaches the Computer with no public address.
- A Computer of your GizStack team is reached the same way with your terminal token (`GIZ_TOKEN`):
  `ssh -o ProxyCommand='giz ssh-proxy %h %p' user@COMPUTER`. `GIZ_ORG` (an id or slug) names the team; without it,
  your personal team.

## Apps

```sh
giz app create --input @app.json
giz app list                                        # each app with its revision
giz app run APP_ID --expected-revision 3
giz app publish APP_ID workspace --expected-revision 3    # private, workspace or public
giz app open APP_ID
giz app delete APP_ID --expected-revision 4
```

- A new app needs `id`, `framework`, `port` and `runtimeProfile`, with `"expectedRevision": 0`. `--input @FILE`
  reads the JSON from a file and `--input -` from standard input.
- `giz app save --input JSON` changes an app; its `expectedRevision` is the revision you read. `run`, `publish` and
  `delete` name it with `--expected-revision`. An older revision is refused, so two editors never overwrite each
  other.

## Plugins, connections and Agents

```sh
giz connection list                                 # connected services and their status
giz plugin search "pdf" --origin catalog            # catalog, skill or mcp
giz plugin install ID
giz plugin install --path /plugins/my-skill
giz plugin disable NAME                             # also enable, update and remove
giz plugin publish /plugins/my-skill --visibility organization
giz agent start --input '{"agentId": "agent:giz", "prompt": "Summarize the orders of this week"}'
giz agent status TURN --wait
giz agent cancel TURN
giz invoke TOOL --input @input.json                 # any giz.ai tool by name; - reads standard input
```

- A plugin is a skill, an MCP server or an agent. `giz plugin inspect DRIVE_PATH` shows one before you
  install it. `giz plugin unpublish RELEASE` withdraws a shared release.
- `giz agent start` starts one Agent turn and prints it. `status --wait` waits for it to end.

## Use Giz from your AI tools

```sh
giz mcp add claude                                  # or codex; --transport stdio (default) or http
giz mcp check
giz skill install
giz engine run claude "Add input validation to the signup form" --dir .
```

- `giz mcp add` registers Giz's MCP server with Claude Code or Codex. With `stdio`, the tool runs
  `giz mcp serve`, which uses your sign-in. With `http`, the tool signs in in the browser. `giz mcp url`
  prints the server's address.
- `giz skill install` installs the Giz Skill for the AI agents on this machine (`npx skills`).
- `giz engine run claude` runs the official Claude Code with your own Claude subscription, in a separate git
  worktree of the repository at `--dir`. It prints progress lines, then the diff, the changed files and a
  summary. Your checkout does not change.

## Update

`giz update` updates an npm installation with the package manager that installed it. A toolchain installed
with the installer updates with `giz upgrade` ([install guide](../start.md#keep-the-toolchain-current)).

## Next steps

- [Built for AI agents](https://gizstack.com/docs/platform/agents): team Agents, their tools, triggers and the Responses API.
- [Deploy to GizStack](https://gizstack.com/docs/platform/deploy): put your own app online.

Use your Giz account from the command line

The giz command also works with your Giz account: AI models, media jobs, Drive, workspace tables, Computers, Apps, plugins and Agents. These commands need no toolchain. The npm package runs them at once after npm install -g @gizai/cli. giz.ai CLI 2.0 had the same commands, options, output and errors, so a script written for 2.0 keeps working.

--json writes the result, or the error, as JSON. Use it in scripts and agents.
--org ORGANIZATION (or GIZ_ORGANIZATION) picks the organization to work in.
--base-url URL (or GIZ_URL) uses another Giz deployment than https://www.giz.ai.
Exit status: 0 success, 1 the request failed or was refused (the error and a hint are on standard error), 2 the command line is wrong.
giz help COMMAND prints the usage of each command.

giz auth login      # confirm the code in the browser; --device only prints the address
giz auth status     # who is signed in
giz auth logout

The sign-in is kept in ~/.config/giz/credentials.json (GIZ_CONFIG names another file). giz.ai CLI 2.0 reads the same file, so both share one sign-in.
The same sign-in also signs giz deploy, giz api and giz publish in to GizStack.
In CI, set GIZ_TOKEN instead of signing in.

API keys and credit

giz api-key create "My app" --scopes giz.inference,giz.read --expires 2027-01-01T00:00:00Z
giz api-key list
giz api-key revoke key_...
giz credits

create shows the key's secret once. Keep it then.
credits prints your purchased and plan credit, when plan credit resets and this month's spend. In a workspace it also prints the monthly budget. Read it before paid batch work.

Models and media

giz model list --type image --search flux
giz model get MODEL                                # the model and its live input schema
giz chat MODEL "Why is the sky blue? Two sentences."
giz chat MODEL --input '{"messages": [{"role": "user", "content": "Hi"}]}'
giz generate image "a lighthouse at dawn" --model MODEL
giz generate video "the lighthouse, waves rising" --image ./lighthouse.png
giz job wait JOB

chat answers at once. generate and model run start a job and print it.
The kinds of generate are image, video, audio, music and talking-head.
--image LOCAL_PATH and --audio LOCAL_PATH upload a reference. --upload FIELD=LOCAL_PATH uploads a file into any input field. --input JSON gives the whole input.
giz job list --limit N, giz job get JOB and giz job cancel JOB manage jobs. giz job wait JOB exits 1 unless the job completed, so a script can stop at a failed job.
giz upload LOCAL_PATH uploads a file and prints its URL, for a model input.

Drive

giz drive ls /
giz drive search "invoice 2026"
giz drive read /notes/plan.md
giz drive write /notes/plan.md --file ./plan.md     # or --content TEXT
giz drive mkdir /reports
giz drive move /notes/plan.md /reports/plan.md
giz drive delete /reports/old.md

Workspace tables

giz table list                                      # the workspace's tables
giz table get task                                  # its fields and actions
giz table read TABLE_PATH --input '{"limit": 20}'
giz table write TABLE_PATH --input '{"create": [{"title": "Call the supplier"}]}'
giz table action task close --id 41,42 --input '{}'

read takes filters, a sort and totals in --input as well as limit. write creates, updates (update, with each row's id) and removes (remove) up to 200 rows, as one change that people can undo.
giz table get lists a table's actions. giz table action runs one on the rows of --id, with the permissions of the person signed in.

Computers

giz computer list
giz computer start NAME                             # also get and stop
giz computer exec --computer NAME --cwd /work -- make test
ssh -o ProxyCommand='giz computer ssh %h %p' user@NAME

exec runs the words after -- on the Computer. Its exit status is the command's. --stdin TEXT or --stdin-file LOCAL_PATH gives its input, and --deadline-ms N stops it after N milliseconds.
Without --computer, a command uses your default Computer.
The ssh line reaches the Computer with no public address.
A Computer of your GizStack team is reached the same way with your terminal token (GIZ_TOKEN): ssh -o ProxyCommand='giz ssh-proxy %h %p' user@COMPUTER. GIZ_ORG (an id or slug) names the team; without it, your personal team.

Apps

giz app create --input @app.json
giz app list                                        # each app with its revision
giz app run APP_ID --expected-revision 3
giz app publish APP_ID workspace --expected-revision 3    # private, workspace or public
giz app open APP_ID
giz app delete APP_ID --expected-revision 4

A new app needs id, framework, port and runtimeProfile, with "expectedRevision": 0. --input @FILE reads the JSON from a file and --input - from standard input.
giz app save --input JSON changes an app; its expectedRevision is the revision you read. run, publish and delete name it with --expected-revision. An older revision is refused, so two editors never overwrite each other.

Plugins, connections and Agents

giz connection list                                 # connected services and their status
giz plugin search "pdf" --origin catalog            # catalog, skill or mcp
giz plugin install ID
giz plugin install --path /plugins/my-skill
giz plugin disable NAME                             # also enable, update and remove
giz plugin publish /plugins/my-skill --visibility organization
giz agent start --input '{"agentId": "agent:giz", "prompt": "Summarize the orders of this week"}'
giz agent status TURN --wait
giz agent cancel TURN
giz invoke TOOL --input @input.json                 # any giz.ai tool by name; - reads standard input

A plugin is a skill, an MCP server or an agent. giz plugin inspect DRIVE_PATH shows one before you install it. giz plugin unpublish RELEASE withdraws a shared release.
giz agent start starts one Agent turn and prints it. status --wait waits for it to end.

Use Giz from your AI tools

giz mcp add claude                                  # or codex; --transport stdio (default) or http
giz mcp check
giz skill install
giz engine run claude "Add input validation to the signup form" --dir .

giz mcp add registers Giz's MCP server with Claude Code or Codex. With stdio, the tool runs giz mcp serve, which uses your sign-in. With http, the tool signs in in the browser. giz mcp url prints the server's address.
giz skill install installs the Giz Skill for the AI agents on this machine (npx skills).
giz engine run claude runs the official Claude Code with your own Claude subscription, in a separate git worktree of the repository at --dir. It prints progress lines, then the diff, the changed files and a summary. Your checkout does not change.

Update

giz update updates an npm installation with the package manager that installed it. A toolchain installed with the installer updates with giz upgrade (install guide).

Next steps

Built for AI agents: team Agents, their tools, triggers and the Responses API.
Deploy to GizStack: put your own app online.